test: epoc32/include/mw/eikmfne.h@2fe1408b6811

     1 /*

     2 * Copyright (c) 1997-1999 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    19 #if !defined(__EIKMFNE_H__)

    20 #define __EIKMFNE_H__

    22 #if !defined(__EIKBCTRL_H__)

    23 #include <eikbctrl.h>

    24 #endif

    26 #if !defined(__COEDEF_H__)

    27 #include <coedef.h>

    28 #endif

    30 #if !defined(__COEINPUT_H__)

    31 #include <coeinput.h>

    32 #endif

    34 // For MEikCalendarObserver

    35 #if !defined(__EIKCAL_H__)

    36 #include <eikcal.h>

    37 #endif

    39 #if !defined(__EIKDEF_H__)

    40 #include <eikdef.h>

    41 #endif

    43 #if !defined(__BABITFLAGS_H__)

    44 #include <babitflags.h>

    45 #endif

    47 // For MAknMfneCommandObserver

    48 #if !defined(__AKNMFNECOMMANDOBSERVER)

    49 #include <AknMfneCommandObserver.h>

    50 #endif //!defined(__AKNMFNECOMMANDOBSERVER)

    52 //

    53 // Forward Declarations

    54 //

    55 class CEikonEnv;

    56 class CTimeEditor;

    57 class CDateEditor;

    59 // Skin-related API forward declarations

    60 class MAknsControlContext;

    62 // Extension object within CEikMfne

    63 class CEikMfneExtension;

    65 //

    66 /**

    67  * Abstract base class for fields within a multi-field numeric editor.

    68  */

    69 class CEikMfneField : public CBase

    70 	{

    71 public:

    72     /**

    73      * The type of highlight.

    74      */

    75 	enum THighlightType

    76 		{

    77 		/** Inverse video. */

    78 		EInverseVideo,

    79 		/** The cursor is visible in the field so that highlighting is not used. */

    80 		ECursor

    81 		};

    82 protected:

    83     /**

    84      * Protected default constructor.

    85      *

    86      * Sets the minimum width of the field to zero pixels.

    87      */

    88 	IMPORT_C CEikMfneField();

    89 public:

    90 	void Draw(CWindowGc& aGc, const CFont& aFont, const TPoint& aTopLeft) const;

    91 	TInt WidthInPixels(const CFont& aFont) const;

    92 	TInt DistanceFromStartOfFieldToEndOfTextInPixels(const CFont& aFont) const;

    94     /**

    95      * An implementation of this pure virtual function should

    96      * get the field's maximum width in pixels.

    97      *

    98      * @param aFont The font.

    99      * @param aShrinkToMinimumSize ETrue to shrink the width to the minimum required.

   100      * @return The field's maximum width in pixels.

   101      */

   102 	virtual TInt MaximumWidthInPixels(const CFont& aFont, TBool aShrinkToMinimumSize)=0;

   104     /**

   105      * An implementation of this pure virtual function should

   106      * return the field's input capabilities.

   107      *

   108      * @return The field's input capabilities.

   109      */

   110 	virtual TCoeInputCapabilities InputCapabilities() const=0;

   112 	/**

   113 	 * Derived classes' implementation of function should

   114 	 * return whether the field is editable.

   115 	 *

   116 	 * This implementation returns EFalse.

   117 	 *

   118 	 * @return EFalse.

   119      */

   120 	IMPORT_C virtual TBool IsEditable() const;

   122 	/**

   123 	 * Derived classes' implementation of function should

   124 	 * return whether the field is valid

   125 	 *

   126 	 * This implementation returns ETrue.

   127 	 *

   128 	 * @return ETrue.

   129      */

   130 	IMPORT_C virtual TBool IsValid() const;

   132 	/**

   133 	 * An implementation of this function should get the

   134 	 * field's highlight type.

   135      *

   136      * May only be called if IsEditable() returns ETrue.

   137      *

   138      * This implementation panics in debug builds and returns

   139      * a dummy value in release builds.

   140      *

   141      * @return EInverseVideo.

   142      */

   143 	IMPORT_C virtual THighlightType HighlightType() const;

   145 	/**

   146 	 * An implementation of this function should handle a key event.

   147      *

   148      * May only be called if IsEditable() returns ETrue.

   149      * This implementation panics in debug builds and is

   150      * empty in release builds.

   151      *

   152      * @param aFont The control's font.

   153      * @param aKeyEvent The key event passed on from the multi-field numeric editor.

   154      * @param aInterpretLeftAndRightAsEarEvents Not used.

   155      * @param aDataAltered On return, indicates whether or not the field

   156      *                     contents changed. If EFalse, left and right arrow

   157      *                     key presses indicate a movement to the preceding of

   158      *                     following field, if ETrue they are ignored.

   159      * @param aHighlightIncrement On return: -1 indicates the previous field is

   160      *                            highlighted,0 indicates the highlight is

   161      *                            unchanged and 1 indicates the following field

   162      *                            is highlighted.

   163      */

   164 	IMPORT_C virtual void HandleKey(const CFont& aFont, const TKeyEvent& aKeyEvent, TBool aInterpretLeftAndRightAsEarEvents, TBool& aDataAltered, TInt& aHighlightIncrement);

   166  	/**

   167  	* An implementation of this function should

   168  	* handle de-highlighting the field.

   169     *

   170     * May only be called if IsEditable() returns ETrue.

   171     *

   172     * This implementation panics in debug builds and is empty

   173     * in release builds.

   174     *

   175     * @param aFont The control's font.

   176     * @param aEikonEnv The control's environment.

   177     * @param aDataAltered On return, set to ETrue if the function caused

   178     *                     the field's contents to change, otherwise unchanged.

   179     * @param aError On return, changed to ETrue if an error occurred e.g.

   180     *               the user entered an invalid value, otherwise unchanged.

   181     */

   182 	IMPORT_C virtual void HandleDeHighlight(const CFont& aFont, CEikonEnv& aEikonEnv, TBool& aDataAltered, TBool& aError);

   184 	const TDesC& FieldText() const;

   185 protected:

   186     /**

   187      * Handles a left or right arrow key press.

   188      *

   189      * @param aKey Left or right arrow key: either EKeyLeftArrow or EKeyRightArrow.

   190      * @param aDataAltered On return, ETrue if data is altered as a result of this function.

   191      * @param aHighlightIncrement On return, the direction to move the cursor:

   192      *                            either -1 if aKey is a left arrow key, or 1 if aKey is a right arrow key.

   193      * @panic 3 In debug builds, if aKey is neither a left nor a right arrow key.

   194      */

   195 	IMPORT_C void HandleLeftOrRightArrow(TChar aKey, TBool& aDataAltered, TInt& aHighlightIncrement);

   197     TInt AdditionalWidthForHighlights(const CFont& aFont) const;

   198 private:

   199 	virtual const TDesC& Text() const=0;

   200 protected:

   201     /**

   202      * The field's minimum width in pixels.

   203      */

   204 	TInt iMinimumWidthInPixels;

   205 	};

   207 //

   209 /**

   210  * A separator field for a multi-field numeric editor.

   211  *

   212  * For instance, the character that separates time or date components.

   213  */

   214 NONSHARABLE_CLASS(CEikMfneSeparator) : public CEikMfneField

   215 	{

   216 private:

   217 	CEikMfneSeparator(HBufC* aText);

   218 public:

   219     /**

   220      * Destructor.

   221      *

   222      * Deletes the separator text that is owned by the object.

   223      */

   224 	IMPORT_C virtual ~CEikMfneSeparator();

   226 	/**

   227 	 * Allocates and constructs a CEikMfneSeparator from resource.

   228      *

   229      * Uses an MFNE_SEPARATOR resource.

   230      *

   231      * @param aResourceReader The resource reader to use.

   232      * @return A newly constructed separator field.

   233      */

   234 	IMPORT_C static CEikMfneSeparator* NewL(TResourceReader& aResourceReader);

   236 	/**

   237 	 * Allocates and constructs a separator.

   238      *

   239      * @param aText The separator's text. Ownership of aText is transferred.

   240      * @return A newly constructed separator.

   241      */

   242 	IMPORT_C static CEikMfneSeparator* NewL(HBufC* aText); // ownership of aText is transferred when everything that can leave has successfully been done

   244 	/**

   245 	 * Sets the separator's text.

   246      *

   247      * This function transfers ownership of the text and can only be called if the field's text was previously NULL.

   248      *

   249      * @param aText The separator's text.

   250      * @panic 4 If the separator's text was not previously Null.

   251      */

   252 	IMPORT_C void SetText(HBufC* aText); // allows later transfer of ownership of text - can only be called if aText was previously NULL

   254 private: // framework

   255 	virtual TInt MaximumWidthInPixels(const CFont& aFont, TBool aShrinkToMinimumSize);

   256 	virtual TCoeInputCapabilities InputCapabilities() const;

   257 	virtual const TDesC& Text() const;

   258 private:

   259 	HBufC* iText;

   260 	};

   262 //

   264 /**

   265  * A number field within a multi-field numeric editor.

   266  */

   267 NONSHARABLE_CLASS(CEikMfneNumber) : public CEikMfneField

   268 	{

   269 public:

   270     /**

   271      * Flags for the number field.

   272      *

   273      * EFillWithLeadingZeros, EPreserveOldWidthBeforeEditing and ERepresentsYear can only be set if EPublicallySettableFlags is set.

   274      */

   275 	enum

   276 		{

   277 		/** Prepends the number field's value with leading zeros up to the maximum allowable width of the field. */

   278 		EFillWithLeadingZeros			=0x1,

   279 		/** The field's minimum width in pixels is set to the current text's width in pixels. */

   280 		EPreserveOldWidthBeforeEditing	=0x2,

   281 		/** The number is a year. */

   282 		ERepresentsYear					=0x4,

   283 		/** Used internally to make sure only the previous three values are set. */

   284 		EPublicallySettableFlags		=EFillWithLeadingZeros|EPreserveOldWidthBeforeEditing|ERepresentsYear

   285 		};

   286 private:

   287 	enum

   288 		{

   289 		EIsBeingEditedWithCursor		=0x8,

   290 		EIsUninitialised				=0x10,

   291 		EFillWithTrailingZeros          =0x20

   292 		};

   293 private:

   294 	CEikMfneNumber(TInt aMinimumValue, TInt aMaximumValue, TUint32 aFlags);

   295 	void ConstructL();

   296 public:

   297     /**

   298      * Destructor.

   299      *

   300      * Deletes the number field's text.

   301      */

   302 	IMPORT_C virtual ~CEikMfneNumber();

   304 	/**

   305 	 * Allocates and constructs a CEikMfneNumber from resource.

   306      *

   307      * Obtains flags and the minimum and maximum values from an MFNE_NUMBER resource. Then calls the overloaded NewL() function.

   308      *

   309      * @param aFont The font to use.

   310      * @param aResourceReader The resource reader to use.

   311      * @return A newly constructed number field.

   312 	 */

   313 	IMPORT_C static CEikMfneNumber* NewL(const CFont& aFont, TResourceReader& aResourceReader);

   315     /**

   316      * Allocates and constructs a CEikMfneNumber with the specified parameters.

   317      *

   318      * @param aFont The font to use.

   319      * @param aMinimumValue The minimum value.

   320      * @param aMaximumValue The maximum value.

   321      * @param aInitialValue The initial value. This must be greater than the minimum value and less than the maximum value.

   322      * @param aFlags The number field's flags. See the Anonymous enum.

   323      * @return A newly constructed number field.

   324      * @panic 8 If the initial value is not greater than or equal to the minimum value and less than or equal to the maximum value.

   325      */

   326 	IMPORT_C static CEikMfneNumber* NewL(const CFont& aFont, TInt aMinimumValue, TInt aMaximumValue, TInt aInitialValue, TUint32 aFlags);

   328 	/**

   329 	 * Sets the minimum and maximum allowable values.

   330      *

   331      * @param aMinimumValue The minimum value. Must be less than or equal to the maximum value.

   332      * @param aMaximumValue The maximum value.

   333      * @param aFont The font in use.

   334      * @panic 9 If the minimum value is greater than the maximum value or if the minimum/maximum text length is greater than the maximum number of digits.

   335      */

   336 	IMPORT_C void SetMinimumAndMaximum(TInt aMinimumValue, TInt aMaximumValue, const CFont& aFont); // only values inside the initial minimum and maximum are permitted

   338 	/**

   339 	 * Gets the minimum and maximum allowable values.

   340 	 *

   341 	 * @param aMinimumValue On return, the minimum allowable value.

   342 	 * @param aMaximumValue On return, the maximum allowable value.

   343      */

   344 	IMPORT_C void GetMinimumAndMaximum(TInt& aMinimumValue, TInt& aMaximumValue) const;

   346 	/**

   347 	 * Sets the field's current value.

   348      * @param aValue The field's current value. This must be between the minimum value and the maximum value.

   349      * @param aFont The font.

   350      * @panic 11 In debug builds only, if the value is less than the minimum value or greater than the maximum value.

   351      */

   352 	IMPORT_C void SetValue(TInt aValue, const CFont& aFont);

   354  	/**

   355  	 * Gets the number field's value. Note that this function will leave

   356  	 * if the value is not valid, i.e. the number of digits is zero

   357  	 * or the value is outside of the minimum and maximum range.

   358      *

   359      * @return The field's value.

   360      */

   361 	IMPORT_C TInt Value() const;

   363     /**

   364 	 * Returns ETrue if the field contains more than zero

   365 	 * digits.

   366      *

   367 	 * @return ETrue if the field contains more than zero digits.

   368      */

   369 	IMPORT_C virtual TBool IsValid() const;

   371     /**

   372      * Sets the uninitialized status of the field.

   373      *

   374      * @param aUninitialised If ETrue, sets the field as uninitialized,

   375      *                       i.e. it doesn't display anything.

   376      */

   377 	IMPORT_C void SetUninitialised(TBool aUninitialised);

   379 	/**

   380 	 * Gets the uninitialized status of the field.

   381 	 *

   382 	 * @return ETrue, if the field is set as uninitialized.

   383 	 */

   384 	IMPORT_C TBool IsUninitialised() const;

   386 public:

   387     /**

   388      * Sets the digit display type.

   389      *

   390      * @since S60 v3.1

   391      * @param aDigitType The digit display type to bet set for this number field

   392      * @param aFont The font of the MFNE that owns this field, usually retrieved with CEikMfne::Font()

   393      */

   394 	IMPORT_C void SetDigitType(TDigitType aDigitType, const CFont& aFont);

   396     /**

   397      * Gets the digit display type.

   398      *

   399      * @since S60 v3.1

   400      * @return The digit display type of this number field

   401      */

   402 	IMPORT_C TDigitType DigitType() const;

   404 	/**

   405 	 * Derive and set digit display type from locale information.

   406 	 *

   407 	 * @since S60 v3.1

   408 	 * @param aFont The font of the MFNE that owns this field, usually retrieved with CEikMfne::Font()

   409 	 */

   410 	IMPORT_C void RefreshDigitType(const CFont& aFont);

   412 	void SetTrailingZeros();

   414 public:

   415 	TBool IsTextNull() const;

   416 private: // framework

   417 	virtual TInt MaximumWidthInPixels(const CFont& aFont, TBool aShrinkToMinimumSize);

   418 	virtual TCoeInputCapabilities InputCapabilities() const;

   419 	virtual TBool IsEditable() const;

   420 	virtual THighlightType HighlightType() const;

   421 	virtual void HandleKey(const CFont& aFont, const TKeyEvent& aKeyEvent, TBool aInterpretLeftAndRightAsEarEvents, TBool& aDataAltered, TInt& aHighlightIncrement);

   422 	virtual void HandleDeHighlight(const CFont& aFont, CEikonEnv& aEikonEnv, TBool& aDataAltered, TBool& aError);

   423 	virtual const TDesC& Text() const;

   424 private:

   425 	TInt MaximumNumberOfDigits() const;

   426 	TInt NumberOfDigits() const;

   427 	void SetTextToValue(TInt aValue, const CFont& aFont);

   428 	TInt ValueFromText() const;

   429 	TBool ConvertsIntoValidValue(TInt& aValue) const;

   431 private: // International digit support

   432 	TChar NormalizeDigit(TChar aChar);

   433 	TText ZeroCharacter() const;

   434 	TText NegativeCharacter() const;

   436 private:

   437 	TInt iMinimumValue;

   438 	TInt iMaximumValue;

   439 	TInt iMaxDigits;

   440 	TUint32 iFlags;

   441 	HBufC* iText;

   442 	TChar iNudgeCharMinus;

   443 	TChar iNudgeCharPlus;

   444 	TInt iMaxDigitsMinimumValue;

   445     TInt iMaxDigitsMaximumValue;

   446 	TDigitType	iDigitType;

   447 	};

   449 //

   451 /**

   452  * A symbol field for a multi-field numeric editor.

   453  *

   454  * For instance, the AM / PM text in a time editor. In this case, the field contains 2 symbolic items one each for the AM and PM text strings.

   455  */

   456 NONSHARABLE_CLASS(CEikMfneSymbol) : public CEikMfneField

   457 	{

   458 public:

   459     /**

   460      * An item within a symbol field in an MFNE.

   461      */

   462 	NONSHARABLE_CLASS(CItem) : public CBase

   463 		{

   464 	private:

   465 		CItem(TInt aId, TChar aKeyToMatch, HBufC* aText);

   466 	public:

   467 	    /**

   468 	     * Destructor.

   469          *

   470          * Deletes the item's text.

   471          */

   472 		IMPORT_C virtual ~CItem();

   474 		/**

   475 		 * Allocates and constructs a symbolic item from resource.

   476          *

   477          * Uses a MFNE_SYMBOLIC_ITEM resource.

   478          * @param aResourceReader The resource reader to use.

   479          * @return A newly constructed symbolic item.

   480          */

   481 		IMPORT_C static CItem* NewL(TResourceReader& aResourceReader);

   483 		/**

   484 		 * Allocates and constructs a symbolic item.

   485          *

   486          * @param aId The ID of the symbolic item that uniquely identifies the item in the field.

   487          * @param aKeyToMatch The key that represents the item. This is for character matching, not for display.

   488          * @param aText The text to be drawn. Ownership of aText is transferred when everything that can leave has successfully completed.

   489          * @return A newly constructed symbolic item.

   490          */

   491 		IMPORT_C static CItem* NewL(TInt aId, TChar aKeyToMatch, HBufC* aText); // ownership of aText is transferred when everything that can leave has successfully been done

   493         /**

   494          * Sets the symbolic item's text.

   495          *

   496          * The item takes ownership of aText.

   497          *

   498          * @param aText The symbolic item's text.

   499          * @panic 19 In debug builds if the symbolic item's text was not

   500          *           previously Null.

   501          */

   502 		IMPORT_C void SetText(HBufC* aText); // allows later transfer of ownership of text - can only be called if aText was previously NULL

   503 	private:

   504 		friend class CEikMfneSymbol;

   505 	private:

   506 		TInt iId;

   507 		TCharF iKeyToMatch;

   508 		HBufC* iText;

   509 		};

   510 private:

   511 	CEikMfneSymbol(TInt aNumSymbolicItems);

   512 public:

   513     /**

   514      * Destructor.

   515      *

   516      * Deletes the array of symbolic items owned by the object.

   517      */

   518 	IMPORT_C virtual ~CEikMfneSymbol();

   520 	/**

   521      * Allocates and constructs a CEikMfneSymbol from resource.

   522      *

   523      * Uses a MFNE_SYMBOL resource. The first item is set as current.

   524      *

   525      * @param aResourceReader The resource reader to use.

   526      * @return A newly constructed symbol.

   527      * @panic 15 If there is not more than one symbol.

   528      */

   529 	IMPORT_C static CEikMfneSymbol* NewL(TResourceReader& aResourceReader);

   531     /**

   532      * Allocates and constructs a CEikMfneSymbol.

   533      *

   534      * The first item is set as current.

   535      *

   536      * @param aNumSymbolicItems The number of symbolic items. Must be

   537      * greater than one. All items are set to NULL.

   538      * @return A newly constructed symbol.

   539      * @panic 15 If there is not more than one symbol.

   540      */

   541 	IMPORT_C static CEikMfneSymbol* NewL(TInt aNumSymbolicItems);

   543     /**

   544      * Adds the specified symbolic item at the first available position in

   545      * the array.

   546      *

   547      * This should be called by the container only if construction was not

   548      * made from resource.

   549      *

   550      * @param aSymbolicItem The symbol to add. Ownership of aSymbolicItem

   551      * is transferred to this.

   552      * @param aMakeCurrent ETrue to make the added symbol current.

   553      * @panic 16 In debug build if the symbolic item array has not yet been

   554      * created.

   555      * @panic 17 If the array is full.

   556      */

   557 	IMPORT_C void AddSymbolicItem(CItem* aSymbolicItem, TBool aMakeCurrent); // to be called by container only if not constructed from resource - ownership of aSymbolicItem is transferred to "this"

   559 	/**

   560      * Sets the current item to the one specified.

   561      *

   562      *

   563      * @param aId The id of the new current item.

   564      * @panic 18 If the specified item does not exist.

   565      */

   566 	IMPORT_C void SetCurrentSymbolicItemToId(TInt aId);

   568     /**

   569      * Gets the current symbol's ID.

   570      *

   571      * @return The current symbol's ID.

   572      */

   573 	IMPORT_C TInt IdOfCurrentSymbolicItem() const;

   575     /**

   576      * Sets the uninitialized status of the field.

   577      *

   578      * @param aUninitialised If ETrue, sets the field as uninitialized,

   579      *                       i.e. doesn't display anything.

   580      */

   581 	IMPORT_C void SetUninitialised(TBool aUninitialised);

   583 	/**

   584 	 * Gets the uninitialized status of the field.

   585 	 *

   586 	 * @return ETrue, if the field is set as uninitialized.

   587 	 */

   588 	IMPORT_C TBool IsUninitialised() const;

   590 private: // framework

   591 	virtual TInt MaximumWidthInPixels(const CFont& aFont, TBool aShrinkToMinimumSize);

   592 	virtual TCoeInputCapabilities InputCapabilities() const;

   593 	virtual TBool IsEditable() const;

   594 	virtual THighlightType HighlightType() const;

   595 	virtual void HandleKey(const CFont& aFont, const TKeyEvent& aKeyEvent, TBool aInterpretLeftAndRightAsEarEvents, TBool& aDataAltered, TInt& aHighlightIncrement);

   596 	virtual void HandleDeHighlight(const CFont& aFont, CEikonEnv& aEikonEnv, TBool& aDataAltered, TBool& aError);

   597 	virtual const TDesC& Text() const;

   598 private:

   599 	TInt CurrentSymbolicItem() const;

   600 	void SetCurrentSymbolicItem(TInt aCurrentSymbolicItem);

   601 private:

   602 	TInt iNumSymbolicItems;

   603 	TInt iCurrentSymbolicItem;

   604 	CItem** iSymbolicItems;

   605 	};

   607 //

   609 /**

   610  * Multi-field numeric editor abstract base class.

   611  *

   612  * This is a set of fields, where a field can be a number, a symbol or

   613  * a separator. Field classes are derived from CEikMfneField.

   614  *

   615  * Concrete multi-field numeric editors are derived from this class and

   616  * should provide the following:

   617  *

   618  * * A virtual destructor if the class introduces new data members which

   619  * are allocated on the heap.

   620  *

   621  * * A ConstructL() function; this is used to initialise a multi-field

   622  * numeric editor.

   623  *

   624  * * A ConstructFromResourceL() function; this is used to initialise a

   625  * multi-field numeric editor from a resource.

   626  *

   627  * * A data member to store the editor's value.

   628  *

   629  * * Functions to set and get the editor's value.

   630  *

   631  * * Functions to set the minimum and maximum allowable values.

   632  */

   633 class CEikMfne : public CEikBorderedControl, public MAknMfneCommandObserver

   634 	{

   635 public:

   636 	// miscellaneous functions

   637     /**

   638      * Default constructor.

   639      */

   640 	IMPORT_C CEikMfne();

   642 	/**

   643      * Destructor.

   644      *

   645      * This function is virtual which ensures that if delete is explicitly

   646      * called on a CEikMfne pointer which points to a derived class

   647      * instance, the derived class destructor is called.

   648      */

   649 	IMPORT_C virtual ~CEikMfne();

   651     /**

   652      * Allocates a field array containing aNumFields elements.

   653      *

   654      * This should be called by the container only if a derived control is

   655      * not constructed from a resource.

   656      *

   657      * @param aNumFields The number of fields.

   658      * @panic 20 In debug builds, if there is already a field in the editor.

   659      */

   660 	IMPORT_C void CreateFieldArrayL(TInt aNumFields); // to be called by container only if not constructed from resource

   662     /**

   663      * Adds a field.

   664      *

   665      * The field is added as the first empty element in the field array or,

   666      * if there is no current field, aField becomes the current field.

   667      *

   668      * This should be called by the container only if a derived control is

   669      * not constructed from a resource.

   670      *

   671      * Ownership of aField is transferred to this multi-field numeric

   672      * editor.

   673      *

   674      * @param aField A field.

   675      * @panic 22 If the field array has not been allocated.

   676      */

   677 	IMPORT_C void AddField(CEikMfneField* aField); // to be called by container only if not constructed from resource - ownership of aField is transferred to "this"

   679     /**

   680      * Deletes the editor's field and the field array.

   681      *

   682      * After a call to this, CreateFieldArrayL() can be called again.

   683      */

   684 	IMPORT_C void ResetFieldArray(); // after this CreateFieldArrayL() can be called again

   686 	/**

   687      * Gets the control's border margins.

   688      *

   689      * @return The control's margins.

   690      */

   691 	IMPORT_C TMargins BorderMargins() const;

   693     /**

   694      * Draws immediately, and then leaves with an info message containing a

   695      * formatted time/date string.

   696      *

   697      * The time/date is passed to the function, as is the resource which

   698      * contains the format string which defines how it is to be formatted.

   699      *

   700      * @param aResourceId The resource containing the time/date format. See

   701      * TTime::FormatL().

   702      * @param aTimeDate The object containing the time/date to be displayed.

   703      */

   704 	IMPORT_C void DrawNowAndLeaveWithTimeDateFormatInfoMsgL(TInt aResourceId, const TTime& aTimeDate) const;

   706     /**

   707      * Gets the CEikMfneField at the specified index.

   708      *

   709      * @param aField The field index.

   710      * @return The requested field, or NULL if the index is less than zero

   711      * or greater than the number of fields.

   712      */

   713 	IMPORT_C CEikMfneField* Field(TInt aField) const;

   715 public:

   716 	// some utility functions which other classes may find useful

   718 	/**

   719      * A utility function which reads seconds, minutes and hours from a

   720      * resource and returns the corresponding TTime value.

   721      *

   722      * @param aResourceReader A resource reader.

   723      * @return The time value read from the resource.

   724      */

   725 	IMPORT_C static TTime ReadTime(TResourceReader& aResourceReader);

   727     /**

   728      * A utility function which reads days, months and years from a resource

   729      * and returns the corresponding TTime value.

   730      *

   731      * @param aResourceReader A resource reader.

   732      * @return The date value read from the resource. The hours, minutes,

   733      * seconds values are set to zero.

   734      */

   735 	IMPORT_C static TTime ReadDate(TResourceReader& aResourceReader);

   737     /**

   738      * A utility function which reads seconds, minutes, hours, days, months

   739      * and years from a resource and returns the corresponding TTime value.

   740      *

   741      * @param aResourceReader A resource reader.

   742      * @return The time/date value read from the resource.

   743      */

   744 	IMPORT_C static TTime ReadTimeAndDate(TResourceReader& aResourceReader);

   746     /**

   747      * Reads a duration value from a resource.

   748      *

   749      * @param aResourceReader A resource reader.

   750      * @return The duration, in seconds.

   751      */

   752 	IMPORT_C static TTimeIntervalSeconds ReadDuration(TResourceReader& aResourceReader);

   754     /**

   755      * Reads a time offset from a resource.

   756      *

   757      * This is identical to ReadDuration(), except that negative offsets

   758      * are allowed.

   759      *

   760      * @param aResourceReader A resource reader.

   761      * @return The duration, in seconds.

   762      */

   763 	IMPORT_C static TTimeIntervalSeconds ReadTimeOffset(TResourceReader& aResourceReader);

   765     /**

   766      * Converts a time duration to seconds.

   767      *

   768      * @param aTime The date and time to be converted.

   769      * @return The time duration in seconds.

   770      */

   771 	IMPORT_C static TTimeIntervalSeconds Convert(const TTime& aTime);

   773     /**

   774      * Converts a time duration in seconds to hours, minutes and seconds.

   775      *

   776      * @param aTimeIntervalSeconds The number of seconds to be converted.

   777      * @return The date/time duration.

   778      */

   779 	IMPORT_C static TTime Convert(const TTimeIntervalSeconds& aTimeIntervalSeconds);

   780     //

   781     /**

   782      * Gets the index into the field array of the current field.

   783      *

   784      * @return The current field's index.

   785      */

   786     inline TInt CurrentField() const;

   788     /**

   789      * Gets the number of fields.

   790      *

   791      * @return The number of fields in the editor.

   792      */

   793     inline TInt NumFields() const;

   795 public: // AVKON addition

   796     /**

   797      * Settable features for MFNE. See SetFeature().

   798      *

   799      * @since S60 3.2

   800      */

   801     enum TFeatureId

   802         {

   803         /** Tries to prevent MFNE drawing outside its rect,

   804             event if it smaller than MinimumSize().

   805             0 (or EFalse) parameter disables this, non-zero

   806             (or ETrue) enables the feature. */

   807         EClipGcToRect,

   809         /** Disables VKB. Non-zero (or ETrue) parameter disables VKB,

   810             0 (or EFalse) enables VKB. When disabled,

   811             editor doesn't request PenInputServer to start VKB */

   812         EDisablePenInput,

   814         /** Support finger input. Paramter is TFingerSupportParams.*/

   815         EFingerSupport

   816         };

   817     /** Parameter for finger support feature:

   818       * 0 means disable the suppor;

   819       * 1 means enable the support;

   820       * 2 means enable the support with highlight of whole text.

   821       */

   822     enum TFingerSupportParams

   823         {

   824         EDisaleFingerSupport,

   825         EnableFingerSupport,

   826         EnableWithAllHighlight

   827         };

   829     /**

   830      * Sets the alignment of the editor. The editor alignments, defined in

   831      * avkon.hrh, are EAknEditorAlignNone, EAknEditorAlignCenter,

   832      * EAknEditorAlignLeft, EAknEditorAlignRight or EAknEditorAlignBidi.

   833      *

   834      * @param aAlignment The editor's alignment

   835      */

   836     IMPORT_C void SetMfneAlignment(TInt aAlignment);

   838     /**

   839      * Sets whether the editor consumes up and down key events. If this is

   840      * set to EFalse, the editor returns EKeyWasNotConsumed upon receiving

   841      * EKeyDownArrow or EKeyUpArrow key event and doesn't send the key event to

   842      * the current field.

   843      *

   844      * @param aConsume If EFalse, OfferKeyEventL() returns

   845      * EKeyWasNotConsumed when up and down key events are received.

   846      */

   847     IMPORT_C void SetUpAndDownKeysConsumed(TBool aConsume);

   849     /**

   850      * Used for suppressing all editor's background drawing. This is

   851      * intended for internal use.

   852      *

   853      * Note that when this is set, the background is not drawn with skin

   854      * nor cleared, so the background MUST be drawn by the parent control

   855      * every time the editor changes.

   856      *

   857      * @param aSuppress If ETrue, suppress background drawing

   858      */

   859     IMPORT_C void SetSuppressBackgroundDrawing( TBool aSuppress );

   861     /**

   862      * Used for setting various flag-like features to the editor.

   863      *

   864      * @param aFeatureId The feature id, see TFeatureId

   865      * @param aFeatureParam The feature parameter. This is usually

   866      *                      enabled or disabled. For more info, see

   867      *                      the feature documentation in TFeatureId.

   868      * @return KErrNone if the feature modification succeeded

   869      * @since S60 3.2

   870      **/

   871     IMPORT_C TInt SetFeature( TInt aFeatureId, TInt aFeatureParam );

   873     /**

   874      * Used to getting feature statuses.

   875      *

   876      * @param aFeatureId The feature id, see TFeatureId

   877      * @param aFeatureParam On return, the parameter for the feature

   878      *                      (usually non-zero for an enabled feature

   879      *                      and zero for disabled)

   880      * @return KErrNone if the feature is supported and fetching its value

   881      *                  succeeded

   882      * @since S60 3.2

   883      */

   884     IMPORT_C TInt GetFeature( TInt aFeatureId, TInt& aFeatureParam ) const;

   886     /**

   887      * Used for checking if the editor supports a feature.

   888      * For features, see TFeatureId.

   889      *

   890      * @param aFeatureId

   891      * @return ETrue if the feature is supported

   892      * @since S60 3.2

   893      */

   894     IMPORT_C TBool SupportsFeature( TInt aFeatureId ) const;

   896     // Highlights a field

   897     void HighlightField(  TInt aFieldPosition );

   899     /**

   900      * Gets a pointer to the CFont object that is used to draw the fields in

   901      * this editor.

   902      *

   903      * @return A pointer to the CFont object used to draw the fields in

   904      * this editor.

   905      */

   906 	IMPORT_C const CFont* Font() const;

   908     /**

   909      * Sets the font that is used to draw the fields in this editor.

   910      *

   911      * @param aFont A pointer to a CFont object that is used to draw the

   912      * fields in this editor.

   913      */

   914 	IMPORT_C void SetFont(const CFont* aFont);

   916     /**

   917      * Sets within in the editor an externally owned Skins background control context.

   918      * This background control context will then be used by the editor to draw background.

   919      *

   920      * If this API is not called, then the editor IS skin enabled, (that is CEikMfnes are skin

   921      * enabled by default) but it will try to find a control context with which to perform background

   922      * drawing from the Control Environment, via the Object Provider.

   923      *

   924      * Setting this control context to NULL will have the effect of turning off background

   925      * skinning.

   926      *

   927      * @param aBackgroundControlContext   Control context to store. Not owned. Can be NULL

   928      */

   929     IMPORT_C void SetSkinBackgroundControlContextL( MAknsControlContext* aControlContext );

   932     /**

   933      * From MAknMfneCommandObserver. Allows owning controls to give commands to

   934      * MFNE editors. This is interface was added to enable modifying the current field

   935      * value with touch buttons.

   936      *

   937      * @param aCommand Command ID defined in MAknMfneCommandObserver::TMfneCommand

   938      */

   939     IMPORT_C void HandleMfneCommandL(TInt aCommand);

   941     /**

   942      * Sets the MFNE to use the CCoeControl::OverrideColorL() defined

   943      * color in drawing. If this is set, no skinning will be used

   944      * in drawing.

   945      *

   946      * @param aUseOverrideColors ETrue to make the MFNE use overridden colors.

   947      * @since S60 v3.2

   948      */

   949     IMPORT_C void SetUseOverrideColors( TBool aUseOverrideColors );

   952 public:	// from CCoeControl

   953     /**

   954      * Handles key events.

   955      *

   956      * Overrides CCoeControl::OfferKeyEventL(). The key event is passed

   957      * onto the current field to handle.

   958      *

   959      * @param aKeyEvent The key event.

   960      * @param aType The type of key event.

   961      * @return Indicates whether or not the key event was used by this

   962      * control.

   963      */

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

   966     /**

   967      * Prepares for focus loss.

   968      *

   969      * Overrides CCoeControl::PrepareForFocusLossL().

   970      *

   971      * This function should be called when an attempt is made to remove

   972      * focus from a multi-field numeric editor. It redraws the control, removing

   973      * highlighting from the current field.

   974      *

   975      * It may be overridden in derived classes to test the validity of

   976      * information entered into the editor. Derived class versions should include

   977      * a base function call.

   978      */

   979 	IMPORT_C virtual void PrepareForFocusLossL();

   981     /**

   982      * Gets the minimum size of the control.

   983      *

   984      * Overrides CCoeControl::MinimumSize().

   985      *

   986      * @return The minimum control size.

   987      */

   988 	IMPORT_C virtual TSize MinimumSize();

   990     /**

   991      * Gets the list of logical colours used to draw the control.

   992      *

   993      * The colours are appended to aColorUseList.

   994      *

   995      * Overrides CCoeControl::GetColorUseListL().

   996      *

   997      * @param aColorUseList On return, the colour list.

   998      */

   999 	IMPORT_C virtual void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const; // not available before Release 005u

  1001     /**

  1002      * Handles a change to the control's resources.

  1003      *

  1004      * The types of resources handled are those which are shared across the

  1005      * environment, e.g. colours or fonts.

  1006      *

  1007      * Overrides CCoeControl::HandleResourceChange().

  1008      *

  1009      * @param aType A message UID value.

  1010      */

  1011 	IMPORT_C virtual void HandleResourceChange(TInt aType);			// not available before Release 005u

  1013     /**

  1014      * Gets the total of the input capabilities of all the editor's fields.

  1015      *

  1016      * Overrides CCoeControl::InputCapabilities().

  1017      *

  1018      * If this function is overrided in a subclass, the subclass should

  1019      * obtain this class' InputCapabilities' object provider through

  1020      * TCoeInputCapabilities::ObjectProvider() and set that as a part of

  1021      * the subclass' InputCapabilities object provider chain to ensure

  1022      * maximum functionality.

  1023      *

  1024      * @return The control's input capabilities.

  1025      */

  1026 	IMPORT_C virtual TCoeInputCapabilities InputCapabilities() const;

  1028     /**

  1029      * From @c CCoeControl.

  1030      *

  1031      * Handles pointer events.

  1032      *

  1033      * @param aPointerEvent The pointer event.

  1034      */

  1035 	IMPORT_C virtual void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  1037     /**

  1038      * Retrieves an object of the same type as that encapsulated in aId.

  1039      *

  1040      * Overrides CCoeControl::MopSupplyObject().

  1041      *

  1042      * @param aId An encapsulated object type ID.

  1043      * @return Encapsulates the pointer to the object provided. Note that

  1044      * the encapsulated pointer may be NULL.

  1045      */

  1046 	IMPORT_C virtual TTypeUid::Ptr MopSupplyObject( TTypeUid aId );

  1048 public: // new

  1049     /**

  1050      * Sets the colors for text and background as skin IDs. Please note that

  1051      * bgcolor overrides skinned draw if set

  1052      *

  1053      * @since 3.0

  1054      * @param aAknSkinIDForTextColor ID for text color.

  1055      * @param aAknSkinIDForBgColor ID for background color.

  1056      */

  1057     IMPORT_C void SetSkinTextColorL(TInt aAknSkinIDForTextColor, TInt aAknSkinIDForBgColor=KErrNotFound);

  1059 protected:

  1060 	// framework

  1061     /**

  1062      * Redraws the current field, so removing or displaying the cursor.

  1063      *

  1064      * If the editor has lost focus, the current field is reset to the

  1065      * first editable field.

  1066      *

  1067      * @param aDrawNow Whether to draw the control immediately.

  1068      */

  1069 	IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);

  1071     /**

  1072      * Writes the internal state of the control and its components to

  1073      * aStream.

  1074      *

  1075      * This function is empty in release builds.

  1076      */

  1077 	IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;

  1079 	// miscellaneous functions

  1081     /**

  1082      * Handles the redrawing associated with a change to the current field.

  1083      *

  1084      * Called by OfferKeyEventL(), HandlePointerEventL() and

  1085      * PrepareForFocusLossL().

  1086      *

  1087      * @param aHandleDeHighlight ETrue if the current field has changed so

  1088      * requires de-highlighting.

  1089      * @param aNewCurrentField The index of the field to which the user has

  1090      * moved.

  1091      * @param aOldWidthInPixelsOfOldCurrentField The width in pixels of the

  1092      * previous current field.

  1093      * @param aOldHighlightTypeOfOldCurrentField The highlight type of the

  1094      * previously current field.

  1095      * @param aDataAltered ETrue if the data has been changed.

  1096      * @param aError On return, ETrue if successful, EFalse if not

  1097      * successful.

  1098      */

  1099 	IMPORT_C void HandleInteraction(TBool aHandleDeHighlight, TInt aNewCurrentField, TInt aOldWidthInPixelsOfOldCurrentField,

  1100 								CEikMfneField::THighlightType aOldHighlightTypeOfOldCurrentField, TBool& aDataAltered, TBool& aError);

  1102     /**

  1103      * Empty virtual function.

  1104      *

  1105      * Called by HandleInteraction() when switching from the current field.

  1106      * Can be implemented by derived classes to maintain consistency between

  1107      * fields, e.g. in a range editor.

  1108      *

  1109      * @param aField The current field.

  1110      * @param aDrawAllFields On return, whether all fields have changed and

  1111      * need to be redrawn.

  1112      */

  1113 	IMPORT_C virtual void FieldIsAboutToBeDeHighlighted(CEikMfneField* aField, TBool& aDrawAllFields); // first occurrence of this virtual function - does nothing by default

  1115     /**

  1116      * Gets the size of the multi-field numeric editor.

  1117      *

  1118      * The width is the sum of the maximum widths of every field.

  1119      *

  1120      * @return The size of the multi-field numeric editor.

  1121      */

  1122 	IMPORT_C TSize MfneSize() const;

  1124     /**

  1125      * Gets the size of the multi-field numeric editor.

  1126      *

  1127      * The width is the sum of the maximum widths of every field.

  1128      *

  1129      * @param aShrinkToMinimumSize ETrue to shrink the width to the minimum

  1130      * required for each field.

  1131      * @return The size of the multi-field numeric editor.

  1132      */

  1133 	IMPORT_C TSize MfneSize(TBool aShrinkToMinimumSize);

  1135     IMPORT_C virtual void SizeChanged();

  1137 public:

  1138 	static void InvalidFieldAlert();

  1139 	static void LeaveWithAlert(TInt aResourceId);

  1140 	void GetCursorInfo( TPoint& aPos, TInt& aHeight, TInt& aWidth, TInt& aAscent );

  1141     void ReportUpdate();

  1142     IMPORT_C virtual void MakeVisible(TBool aVisible);

  1143     void SetCurrentField( TInt aCurrentField );

  1144     void SetValidateCallBack( TCallBack aCallBack );

  1145     void ReportStateChangeEventL();

  1147 private:

  1148 	// framework

  1149 	IMPORT_C virtual void Draw(const TRect& aRect) const;

  1151 	// new virtual functions

  1152 	IMPORT_C virtual void CreatePopoutIfRequiredL();

  1153 	// miscellaneous functions

  1154 	void DrawRange(CWindowGc& aGc, TInt aFirstField, TInt aLastField) const;

  1155 	CWindowGc& PreparedGc() const;

  1156 	void SetGcToNormalVideo(CWindowGc& aGc) const;

  1157 	void SetGcToInverseVideo(CWindowGc& aGc) const;

  1158 	void SetGcToDimmedVideo(CWindowGc& aGc) const;

  1159 	void DrawCursor();

  1160 	void HideCursor();

  1161 	IMPORT_C void Reserved_2();

  1162 	IMPORT_C virtual void CEikMfne_Reserved();

  1164 private:

  1165     /**

  1166     * From CAknControl

  1167     */

  1168     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1170 private:

  1171 	enum {ENullIndex=KMaxTInt};

  1173 	/**

  1174 	 * Access to state of whether up/down keys are eaten and used to increment/decrement.  If

  1175 	 * these keys are not consumed, then the events are passed on.

  1176 	 *

  1177 	 * @return EFalse iff Up and Down keys are not consumed (and acted upon)

  1178 	 */

  1179 	TBool ConsumesUpAndDownKeys() const;

  1181 	/**

  1182 	 * This state of enabling means that skinning will actually be drawn

  1183 	 * It is a combination of

  1184 	 * - application is skin enabled

  1185 	 * - current skin has a background or frame bitmap

  1186 	 * It is set during construction and does not change its value after except if the Skin is

  1187 	 * changed, whereupon the control context is re-accessed and checked for bitmaps present

  1188 	 *

  1189 	 * @return EFalse iff background skin will not be drawn.

  1190 	 */

  1191 	TBool SkinningBackground() const;

  1193 	/**

  1194 	 * Checks if app is skin enabled and that the current control context has bitmap.

  1195 	 * If so, then state is set true.

  1196 	 * This should be called at constuction and when HandleResourceChange is called

  1197 	 *

  1198 	 */

  1199 	void EvaluateSkinningBackground();

  1201     /**

  1202      * Access to Skins background control context that is potentially being used by the Editor.

  1203      *

  1204      * This API will first check to see if an control context has been set by API, and if so,

  1205      * return that.  If the background control context has been set to NULL by API, then it will

  1206      * return NULL. If the background control context has never been set by API, then this returns

  1207      * the control context (if one exists) that the object obtains from Object Provider.

  1208      *

  1209      * @return Pointer to control context potentially in use, or NULL.

  1210      */

  1211     MAknsControlContext* SkinBackgroundControlContext() const;

  1213     /**

  1214      * Check for the existence of the extension and create if required.

  1215      */

  1216     void CreateExtensionIfRequiredL();

  1218 private:

  1219 	TInt iNumFields;

  1220 	TInt iCurrentField;

  1221 	CEikMfneField** iFields;

  1222 	CEikMfneExtension* iExtension;

  1223 	const CFont* iFont;

  1224     TInt iAlignment;

  1225     TBitFlags iFlags;

  1226 	};

  1228 inline TInt CEikMfne::CurrentField() const

  1229     {

  1230     return(iCurrentField);

  1231     }

  1233 inline TInt CEikMfne::NumFields() const

  1234     {

  1235     return(iNumFields);

  1236     }

  1238 //

  1240 /**

  1241  * Integer editor.

  1242  *

  1243  * This control supports editing a single integer value. If a number is

  1244  * entered which is not within the range specified by the maximum and

  1245  * minimum control values it is automatically reset to the nearest

  1246  * allowable value.

  1247  *

  1248  * The editor has an associated resource struct NUMBER_EDITOR and

  1249  * control factory identifier EEikCtNumberEditor.

  1250  */

  1251 class CEikNumberEditor : public CEikMfne

  1252 	{

  1253 public:

  1254 	// miscellaneous functions

  1256     /**

  1257      * Constructor.

  1258      *

  1259      * This function should be used as the first stage in two stage

  1260      * construction, followed by a call to either ConstructFromResourceL() to

  1261      * initialise the editor's field values from a resource file, or ConstructL()

  1262      * if no resource file is used.

  1263      */

  1264 	IMPORT_C CEikNumberEditor();

  1266 	/**

  1267      * Second-phase constructor.

  1268      *

  1269      * Completes the construction of an integer editor. It should be called

  1270      * by container only if the editor is not constructed from a resource.

  1271      *

  1272      * Sets the minimum and maximum values that can be entered into the

  1273      * editor, and the initial value.

  1274      *

  1275      * @param aMinimumValue The minimum allowable value.

  1276      * @param aMaximumValue The maximum allowable value.

  1277      * @param aInitialValue The initial value.

  1278      */

  1279 	IMPORT_C void ConstructL(TInt aMinimumValue, TInt aMaximumValue, TInt aInitialValue); // to be called by container only if not constructed from resource

  1281     /**

  1282      * Sets the minimum and maximum editor values.

  1283      *

  1284      * Only values inside the initial minimum and maximum are permitted.

  1285      *

  1286      * If the editor's value is outside the new bounds when the function is

  1287      * called, it is reset to the nearest allowable value.

  1288      *

  1289      * @param aMinimumValue The minimum allowable value.

  1290      * @param aMaximumValue The maximum allowable value.

  1291      * @panic 9 If the minimum is greater than the maximum allowable value.

  1292      */

  1293 	IMPORT_C void SetMinimumAndMaximum(TInt aMinimumValue, TInt aMaximumValue); // only values inside the initial minimum and maximum are permitted

  1295     /**

  1296      * Gets the integer editor's minimum and maximum values.

  1297      *

  1298      * @param aMinimumValue On return, contains the integer editor's

  1299      * minimum allowable value.

  1300      * @param aMaximumValue On return, contains the integer editor's

  1301      * maximum allowable value.

  1302      */

  1303 	IMPORT_C void GetMinimumAndMaximum(TInt& aMinimumValue, TInt& aMaximumValue) const;

  1305     /**

  1306      * Sets the integer editor's value.

  1307      *

  1308      * The control is not redrawn.

  1309      *

  1310      * @param aNumber The editor's new value.

  1311      * @panic 11 In debug builds, if aNumber is outside the valid range.

  1312      */

  1313 	IMPORT_C void SetNumber(TInt aNumber);

  1315     /**

  1316      * Gets the integer editor's value.

  1317      *

  1318      * @return The integer editor's value.

  1319      * @panic 12 In debug builds, if the editor has no content.

  1320      */

  1321 	IMPORT_C TInt Number() const; // can only be called if PrepareForFocusLossL() succeeded

  1323 	// framework

  1325 	/**

  1326      * Second-phase construction from a resource file.

  1327      *

  1328      * The function reads the maximum and minimum editor values from a

  1329      * NUMBER_EDITOR resource, and sets the initial number to be the same as the

  1330      * maximum value.

  1331      *

  1332      * @param aResourceReader A resource file reader.

  1333      */

  1334 	IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

  1336     // From CCoeControl

  1338     /**

  1339      * From @c CCoeControl.

  1340      *

  1341      * Handles pointer events.

  1342      *

  1343      * @param aPointerEvent The pointer event.

  1344      */

  1345     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  1346 private:

  1347 	IMPORT_C virtual void CEikMfne_Reserved();

  1348 private:

  1349 	void RefreshFromLocale();

  1350 private:

  1351     /**

  1352     * From CAknControl

  1353     */

  1354     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1355 private:

  1356 	// none of these pointers owns anything

  1357 	CEikMfneNumber* iNumber;

  1358 	TInt iSpare;

  1359 	};

  1362 //

  1363 /**

  1364  * Range struct for CEikRangeEditor.

  1365  */

  1366 struct SEikRange

  1367 	{

  1368 	/**

  1369 	 * The lower limit.

  1370 	 */

  1371 	TInt iLowerLimit;

  1373 	/**

  1374 	 * The upper limit.

  1375 	 */

  1376 	TInt iUpperLimit;

  1377 	};

  1379 //

  1381 /**

  1382  * Numeric range editor.

  1383  *

  1384  * This editor supports editing an integer range. It has two fields;

  1385  * the first represents the lower value and the second the upper value. The

  1386  * second value must be greater than, or equal to, the first.

  1387  *

  1388  * Minimum and maximum values for the editor are specified during

  1389  * construction. If a number is entered which is not within the editor's

  1390  * minimum and maximum values, it is automatically reset to the nearest

  1391  * allowable value.

  1392  *

  1393  * The editor has an associated resource struct RANGE_EDITOR and

  1394  * control factory identifier EEikCtRangeEditor.

  1395  */

  1396 class CEikRangeEditor : public CEikMfne

  1397 	{

  1398 public:

  1399 	// miscellaneous functions

  1401     /**

  1402      * Default constructor.

  1403      *

  1404      * This function should be used as the first stage in two stage

  1405      * construction, followed by a call to either ConstructFromResourceL() to

  1406      * initialise the editor's field values from a resource file, or ConstructL()

  1407      * if no resource file is used.

  1408      */

  1409 	IMPORT_C CEikRangeEditor();

  1411 	// ConstructL to be called by container only if not constructed from resource, also ownership of aSeparatorText is transferred when everything that can leave has successfully been done

  1412     /**

  1413      * Second phase constructor.

  1414      *

  1415      * This function completes construction of a range editor. It sets the

  1416      * minimum and maximum values, initial range and separator text. It

  1417      * should be called by the container only if the control is not constructed

  1418      * from a resource file.

  1419      *

  1420      * @param aMinimumValue The minimum value for the range editor.

  1421      * @param aMaximumValue The maximum value for the range editor.

  1422      * @param aInitialRange Struct containing upper and lower range limits.

  1423      * Must be within the minimum and maximum values.

  1424      * @param aSeparatorText The text to be used to separate the numeric

  1425      * values.

  1426      * @panic 8 If the initial lower or upper limit is outside the minimum

  1427      * or maximum bounds.

  1428      */

  1429 	IMPORT_C void ConstructL(TInt aMinimumValue, TInt aMaximumValue, const SEikRange& aInitialRange, HBufC* aSeparatorText);

  1431     /**

  1432      * Sets the range editor's minimum and maximum values.

  1433      *

  1434      * Any values are permitted. If the range values are outside the new

  1435      * minimum / maximum they are changed to be within the new minimum /

  1436      * maximum.

  1437      *

  1438      * @param aMinimumValue The minimum value for the range editor.

  1439      * @param aMaximumValue The maximum value for the range editor.

  1440      */

  1441 	IMPORT_C void SetMinimumAndMaximum(TInt aMinimumValue, TInt aMaximumValue); // only values inside the initial minimum and maximum are permitted

  1443     /**

  1444      * Gets the range editor's minimum and maximum values.

  1445      *

  1446      * @param aMinimumValue On return, the minimum value for the range

  1447      * editor.

  1448      * @param aMaximumValue On return, the maximum value for the range

  1449      * editor.

  1450      */

  1451 	IMPORT_C void GetMinimumAndMaximum(TInt& aMinimumValue, TInt& aMaximumValue) const;

  1453     /**

  1454      * Sets the range editor's current values.

  1455      *

  1456      * @param aRange Struct containing new range values.

  1457      */

  1458 	IMPORT_C void SetRange(const SEikRange& aRange);

  1460     /**

  1461      * Gets the range editor's current values.

  1462      *

  1463      * Can only be called if CEikMfne::PrepareForFocusLossL() succeeded

  1464      *

  1465      * @return Struct containing current range values.

  1466      */

  1467 	IMPORT_C SEikRange Range() const; // can only be called if PrepareForFocusLossL() succeeded

  1469 	// framework

  1471     /**

  1472      * Second phase constructor from resource.

  1473      *

  1474      * This function completes construction of a newly-allocated range

  1475      * editor. It sets the minimum and maximum values, initial range and

  1476      * separator text as specified by the resource.

  1477      *

  1478      * @param aResourceReader A resource reader.

  1479      */

  1480 	IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

  1482     // From CCoeControl

  1484     /**

  1485      * From @c CCoeControl.

  1486      *

  1487      * Handles pointer events.

  1488      *

  1489      * @param aPointerEvent The pointer event.

  1490      */

  1491     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  1492 private:

  1493 	virtual void FieldIsAboutToBeDeHighlighted(CEikMfneField* aField, TBool& aDrawAllFields);

  1494 	IMPORT_C virtual void CEikMfne_Reserved();

  1495 	void RefreshFromLocale();

  1496 private:

  1497     /**

  1498     * From CAknControl

  1499     */

  1500     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1501 private:

  1502 	// none of these pointers owns anything

  1503 	CEikMfneNumber* iLowerLimit;

  1504 	CEikMfneNumber* iUpperLimit;

  1505 	TInt iSpare;

  1506 	};

  1509 //

  1511 /**

  1512  * Specifies an abstract interface for time and date editors where the

  1513  * time and date are set and retrieved using the TTime class.

  1514  */

  1515 class CEikTTimeEditor : public CEikMfne

  1516 	{

  1517 public:

  1518     /**

  1519      * An implementation (of this pure virtual function) should set the

  1520      * range of allowable time values.

  1521      *

  1522      * This defines the maximum and minimum values that may be entered by

  1523      * the user.

  1524      *

  1525      * @param aMinimumTime The minimum allowable value.

  1526      * @param aMaximumTime The maximum allowable value.

  1527      */

  1528 	virtual void SetMinimumAndMaximum(const TTime& aMinimumTime, const TTime& aMaximumTime)=0;

  1530     /**

  1531      * An implementation (of this pure virtual function) should get the

  1532      * range of allowable time values.

  1533      *

  1534      * @param aMinimumTime The minimum allowable value.

  1535      * @param aMaximum The maximum allowable value.

  1536      */

  1537 	virtual void GetMinimumAndMaximum(TTime& aMinimumTime, TTime& aMaximum) const=0;

  1539     /**

  1540      * An implementation (of this pure virtual function) should set the time

  1541      * in the editor.

  1542      *

  1543      * @param aTime The time.

  1544      */

  1545 	virtual void SetTTime(const TTime& aTime)=0;

  1547     /**

  1548      * An implementation (of this pure virtual function) should get the time

  1549      * from the editor.

  1550      *

  1551      * Can only be called if CEikMfne::PrepareForFocusLossL() succeeded.

  1552      *

  1553      * @return The time.

  1554      */

  1555 	virtual TTime GetTTime() const=0; // can only be called if PrepareForFocusLossL() succeeded

  1556 	};

  1558 /**

  1559  * Time editor.

  1560  *

  1561  * This control allows a time value to be displayed and edited. By

  1562  * default the editor has hours, minutes and seconds fields, although the

  1563  * seconds and hours fields may be omitted. 12 and 24-hour format are

  1564  * supported. When 12-hour format is used, am or pm text will be included as

  1565  * another field, either before or after the time. Locale information is

  1566  * used to determine the time separator characters. Locale information is

  1567  * set and retrieved using class TLocale.

  1568  *

  1569  * The upper and lower field bounds are set depending on the format,

  1570  * and times outside these bounds are invalid.

  1571  *

  1572  * The editor has an associated resource struct TIME_EDITOR and control

  1573  * factory identifier EEikCtTimeEditor.

  1574  */

  1575 class CEikTimeEditor : public CEikTTimeEditor

  1576 	{

  1577 public:

  1578 	// miscellaneous functions

  1579     /**

  1580      * Default constructor.

  1581      *

  1582      * This function should be used as the first stage in two stage

  1583      * construction, followed by a call to either: ConstructFromResourceL() to

  1584      * initialise the editor's field values from a resource file, or ConstructL()

  1585      * if no resource file is used.

  1586      */

  1587 	IMPORT_C CEikTimeEditor();

  1589     /**

  1590      * Destructor.

  1591      *

  1592      * This frees the resources owned by the time editor, prior to its

  1593      * destruction.

  1594      */

  1595 	IMPORT_C virtual ~CEikTimeEditor();

  1597     /**

  1598      * Second phase construction.

  1599      *

  1600      * This function completes the construction of a newly-allocated time

  1601      * editor, by setting its minimum, maximum and initial values, and the

  1602      * AM/PM text settings - the AM/PM settings and time separator characters

  1603      * specified in class TLocale are honoured. It should be called by the

  1604      * container only if the control is not constructed from a resource file.

  1605      *

  1606      * If the initial time is outside the bounds specified, it is reset to

  1607      * the nearest available setting.

  1608      *

  1609      * The aFlags parameter is used to determine whether the seconds or

  1610      * hours fields are required. The minutes field is always present. It may

  1611      * also be used to specify whether or not to force 24 hour time format,

  1612      * overriding the locale's setting.

  1613      *

  1614      * A panic will occur if the minimum time is later than the maximum

  1615      * time.

  1616      *

  1617      * @param aMinimumTime The minimum allowable time.

  1618      * @param aMaximumTime The maximum allowable time.

  1619      * @param aInitialTime The initial time.

  1620      * @param aFlags Determines which fields are required and whether or

  1621      * not to force 24 hour formatting. See eikon.hrh EEiktime etc.

  1622      */

  1623 	IMPORT_C void ConstructL(const TTime& aMinimumTime, const TTime& aMaximumTime, const TTime& aInitialTime, TUint32 aFlags); // to be called by container only if not constructed from resource

  1625     /**

  1626      * Sets the time editor's value.

  1627      *

  1628      * @param aTime The new value to which to set the editor's fields.

  1629      */

  1630 	IMPORT_C void SetTime(const TTime& aTime);

  1632     /**

  1633      * Gets the time editor's value.

  1634      *

  1635      * @return The editor's value. (Date values are all zero.)

  1636      */

  1637 	IMPORT_C TTime Time() const;

  1639     /**

  1640      * Sets the uninitialized status of the editor.

  1641      *

  1642      * @param aUninitialised If ETrue, sets the editor as uninitialized,

  1643      *                       i.e. it doesn't display anything.

  1644      */

  1645 	IMPORT_C void SetUninitialised(TBool aUninitialised);

  1647 	/**

  1648 	 * Gets the uninitialized status of the editor.

  1649 	 *

  1650 	 * @return ETrue, if the editor is set as uninitialized.

  1651 	 */

  1652 	IMPORT_C TBool IsUninitialised() const;

  1653 	// from CEikTTimeEditor

  1655     /**

  1656      * Sets the range of allowable time values.

  1657      *

  1658      * These define the maximum and minimum values that may be entered by

  1659      * the user.

  1660      *

  1661      * If the existing time value is outside the bounds set by this

  1662      * function, it is reset to the nearest boundary value.

  1663      *

  1664      * @param aMinimumTime The minimum allowable value.

  1665      * @param aMaximumTime The maximum allowable value.

  1666      * @panic 38 If the minimum value exceeds the maximum.

  1667      */

  1668 	IMPORT_C virtual void SetMinimumAndMaximum(const TTime& aMinimumTime, const TTime& aMaximumTime); // only values inside the initial minimum and maximum are permitted

  1670     /**

  1671      * Gets the range of allowable values that may be entered by the user.

  1672      *

  1673      * @param aMinimumTime On return, contains the time editor's minimum

  1674      * allowable value.

  1675      * @param aMaximumTime On return, contains the time editor's maximum

  1676      * allowable value.

  1677      */

  1678 	IMPORT_C virtual void GetMinimumAndMaximum(TTime& aMinimumTime, TTime& aMaximumTime) const;

  1680 	// from CCoeControl

  1682     /**

  1683      * Second phase construction from a resource.

  1684      *

  1685      * This function completes the construction of a newly-allocated time

  1686      * editor from a TIME_EDITOR resource. The minimum and maximum times, and

  1687      * the flags settings are read from the resource, and ConstructL() is

  1688      * called with these settings. The initial time is set to the maximum time

  1689      * value. Honours the locale's AM/PM text setting and time separators.

  1690      *

  1691      * @param aResourceReader A resource file reader.

  1692      *

  1693      */

  1694 	IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

  1696     /**

  1697      * Prepares the editor for focus loss.

  1698      *

  1699      * This function should be called to validate the editor's contents

  1700      * when an attempt is made to remove focus from the control. If the control

  1701      * value is not within the bounds specified by the minimum and maximum

  1702      * time values, it is reset to the nearest allowable value, the function

  1703      * will leave and will display an appropriate message.

  1704      */

  1705 	IMPORT_C virtual void PrepareForFocusLossL();

  1707     /**

  1708      * From @c CCoeControl.

  1709      *

  1710      * Handles pointer events.

  1711      *

  1712      * @param aPointerEvent The pointer event.

  1713      */

  1714     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  1715 private:

  1716 	// from CEikTTimeEditor

  1717 	virtual void SetTTime(const TTime& aTime);

  1718 	virtual TTime GetTTime() const; // can only be called if PrepareForFocusLossL() succeeded

  1719 private:

  1720 	// miscellaneous functions

  1721 	void DoSetMinimumAndMaximum(const TTime& aMinimumTime, const TTime& aMaximumTime);

  1722 	IMPORT_C virtual void CEikMfne_Reserved();

  1723 private:

  1724     /**

  1725     * From CAknControl

  1726     */

  1727     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1728 private:

  1729 	CTimeEditor* iTimeEditor;

  1730 	TTime iMinimumTime;

  1731 	TTime iMaximumTime;

  1732 	TInt iSpare;

  1733 	};

  1736 //

  1738 // note: TDateTime uses zero based day numbers, so -1 on the day field

  1739 #define KAknMinimumDate (TTime(TDateTime(0001, EJanuary, 1-1, 0, 0, 0, 0)))

  1740 #define KAknMaximumDate (TTime(TDateTime(9999, EDecember, 31-1, 23, 59, 59, 999999)))

  1742 /**

  1743  * Date editor.

  1744  *

  1745  * A date editor has five fields: day, month and year, and two separator

  1746  * characters. The order of the fields varies depending on the locale's

  1747  * date format setting. Locale information, which is set and retrieved using

  1748  * class @c TLocale, is used to determine field order and the characters used

  1749  * to separate the date components. The upper and lower field bounds are set,

  1750  * and dates outside these bounds are invalid.

  1751  *

  1752  * The editor can be configured to launch a pop-out calendar dialog,

  1753  * @c CEikCalendar. This may be used to directly set the day, month and year

  1754  * values.

  1755  *

  1756  * The editor has an associated resource struct @c DATE_EDITOR and control

  1757  * factory identifier @c EEikCtDateEditor.

  1758  *

  1759  */

  1760 class CEikDateEditor : public CEikTTimeEditor, private MEikCalendarObserver

  1761 	{

  1763 public:

  1765     // miscellaneous functions

  1766     /**

  1767      * C++ default constructor.

  1768      */

  1769     IMPORT_C CEikDateEditor();

  1771     /**

  1772      * Destructor.

  1773      */

  1774     IMPORT_C virtual ~CEikDateEditor();

  1776     // to be called by container only if not constructed from resource

  1777     /**

  1778      * Handles 2nd phase construction.

  1779      *

  1780      * This function completes the construction of a newly-allocated date

  1781      * editor. This function should be used instead of

  1782      * @c ConstructFromResourceL() when not initialising from a resource file.

  1783      * The editor's minimum, maximum and initial date values are set and the

  1784      * date format and date separator characters specified in class @c TLocale

  1785      * are honoured.

  1786      *

  1787      * @param aMinimumDate The minimum allowable date.

  1788      * @param aMaximumDate The maximum allowable date.

  1789      * @param aInitialDate The initial value.

  1790      * @param aWithoutPopoutCalendar If @c ETrue the editor will not have a

  1791      *        pop-out calendar dialog / icon. If @c EFalse the editor will have

  1792      *        a pop-out calendar dialog / icon.

  1793      */

  1794     IMPORT_C void ConstructL(const TTime& aMinimumDate,

  1795                              const TTime& aMaximumDate,

  1796                              const TTime& aInitialDate,

  1797                              TBool aWithoutPopoutCalendar);

  1799     /**

  1800      * Sets the date editor's value.

  1801      *

  1802      * @param aDate The editor's value. Time components are ignored.

  1803      */

  1804     IMPORT_C void SetDate(const TTime& aDate);

  1806     /**

  1807      * Gets the date editor's value.

  1808      *

  1809      * @return The editor's date value.

  1810      */

  1811 	IMPORT_C TTime Date() const;

  1813     /**

  1814      * Sets date editor to initialised or uninitialised.

  1815      *

  1816      * @param aUninitialised If @c ETrue then the date editor is set

  1817      *        to be uninitialised.

  1818      */

  1819 	IMPORT_C void SetUninitialised(TBool aUninitialised);

  1821     /**

  1822      * Tests whether the editor is uninitialised.

  1823      *

  1824      * @return @c ETrue if uninitialised.

  1825      */

  1826 	IMPORT_C TBool IsUninitialised() const;

  1828 	// from CEikTTimeEditor

  1829 	// only values inside the initial minimum and maximum are permitted

  1830     /**

  1831      * From @c CEikTTimeEditor.

  1832      *

  1833      * Sets the minimum and maximum allowable dates.

  1834      *

  1835      * If the current date is outside the new bounds it is changed to be within

  1836      * them.

  1837      *

  1838      * @param aMinimumDate The minimum allowable value.

  1839      * @param aMaximumDate The maximum allowable value.

  1840      */

  1841     IMPORT_C virtual void SetMinimumAndMaximum(const TTime& aMinimumDate,

  1842                                                const TTime& aMaximumDate);

  1844     /**

  1845      * From @c CEikTTimeEditor.

  1846      *

  1847      * Gets the date editor's minimum and maximum values.

  1848      *

  1849      * @param aMinimumDate On return, the minimum allowable value.

  1850      * @param aMaximumDate On return, the maximum allowable value.

  1851      */

  1852     IMPORT_C virtual void GetMinimumAndMaximum(TTime& aMinimumDate,

  1853                                                TTime& aMaximumDate) const;

  1855     // from CCoeControl

  1856     /**

  1857      * From @c CCoeControl.

  1858      *

  1859      * Handles key events.

  1860      *

  1861      * @param aKeyEvent The key event.

  1862      * @param aType The type of key event.

  1863      * @return @c EKeyConsumed if the key has beend handled.

  1864      */

  1865     IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

  1866                                                  TEventCode aType);

  1868     /**

  1869      * From @c CCoeControl.

  1870      *

  1871      * Second-phase construction from a resource file.

  1872      *

  1873      * The function reads the maximum and minimum date values and whether

  1874      * or not the editor should support a pop-out calendar and/or date icon

  1875      * from a @c DATE_EDITOR resource. It sets the initial date to be the same

  1876      * as the maximum date and honours the locale's date format and separators.

  1877      *

  1878      * @param aResourceReader A resource file reader.

  1879      */

  1880     IMPORT_C virtual void ConstructFromResourceL(TResourceReader&

  1881                                                  aResourceReader);

  1883     /**

  1884      * From @c CCoeControl.

  1885      *

  1886      * Editor validation.

  1887      *

  1888      * This function should be called before an attempt is made to remove focus

  1889      * from a date editor. If the control value is not within the bounds

  1890      * specified by the minimum and maximum date values, it is reset to the

  1891      * nearest allowable value, the function then leaves.

  1892      */

  1893     IMPORT_C virtual void PrepareForFocusLossL();

  1895     /**

  1896      * From @c CCoeControl.

  1897      *

  1898      * Handles pointer events.

  1899      *

  1900      * @param aPointerEvent The pointer event.

  1901      */

  1902     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  1904 private:

  1906     // from CEikMfne

  1907     virtual void CreatePopoutIfRequiredL();

  1908     // from CEikTTimeEditor

  1909     virtual void SetTTime(const TTime& aDate);

  1910     virtual TTime GetTTime() const; // can only be called if PrepareForFocusLossL() succeeded

  1912 private:

  1914     // from MEikCalendarDialogObserver

  1915     virtual void GetMinimumAndMaximumAndInitialDatesForCalendarL(TTime& aMinimumDate,

  1916                                                                  TTime& aMaximumDate,

  1917                                                                  TTime& aInitialDate) const;

  1918     virtual void SetDateFromCalendarAndDrawNow(const TTime& aDate);

  1919     // miscellaneous functions

  1920     void DoSetMinimumAndMaximum(const TTime& aMinimumDate, const TTime& aMaximumDate);

  1921     IMPORT_C virtual void CEikMfne_Reserved();

  1923 private:

  1925     /**

  1926     * From CAknControl

  1927     */

  1928     IMPORT_C void* ExtensionInterface( TUid aInterface );

  1930 private:

  1932 	CDateEditor* iDateEditor;

  1933 	TTime iMinimumDate;

  1934 	TTime iMaximumDate;

  1935 	TInt iSpare;

  1936 	};

  1939 //

  1941 /**

  1942  * Time and date editor.

  1943  *

  1944  * This control allows both a time and date to be displayed and edited.

  1945  * It contains the following time fields: hours, minutes and seconds,

  1946  * two time separator characters and am/pm text, and the following date

  1947  * fields: year, month and day, with two date separator characters. The

  1948  * seconds and hours fields are optional and the order of the date fields and

  1949  * the separator characters are locale-dependent. The upper and lower

  1950  * field bounds are set, and dates and times outside these bounds are

  1951  * invalid.

  1952  *

  1953  * Date field values may be edited directly or via a pop-out calendar

  1954  * dialog.

  1955  *

  1956  * The editor has an associated resource struct TIME_AND_DATE_EDITOR

  1957  * and control factory identifier EEikCtTimeAndDateEditor.

  1958  */

  1959 class CEikTimeAndDateEditor : public CEikTTimeEditor, private MEikCalendarObserver

  1960 	{

  1961 public:

  1962 	// miscellaneous functions

  1964     /**

  1965      * Default constructor.

  1966      *

  1967      * This function should be used as the first stage in two stage

  1968      * construction, followed by a call to either ConstructFromResourceL() to

  1969      * initialise the editor's field values from a resource file, or ConstructL()

  1970      * (if no resource file is used).

  1971      */

  1972 	IMPORT_C CEikTimeAndDateEditor();

  1974     /**

  1975      * Destructor.

  1976      *

  1977      * This frees the resources owned by the time and date editor, prior to

  1978      * its destruction.

  1979      */

  1980 	IMPORT_C virtual ~CEikTimeAndDateEditor();

  1982 	// ConstructL to be called by container only if not constructed from resource, also ownership of aInterveningText is transferred when everything that can leave has successfully been done

  1984     /**

  1985      * Second phase construction.

  1986      *

  1987      * This function completes construction of a newly-allocated date and

  1988      * time editor, by setting the minimum, maximum and initial date and time

  1989      * values. It should be called by the container only if the control is

  1990      * not constructed from a resource file.

  1991      *

  1992      * The aFlags parameter is used to set whether the seconds or hours

  1993      * fields are not required. The minutes field is always present. It may also

  1994      * be used to specify whether or not to force 24 hour time format,

  1995      * overriding the locale's setting, and whether the editor should have a

  1996      * pop-out calendar dialog.

  1997      *

  1998      * The locale-dependant date and time settings specified in class

  1999      * TLocale are honoured.

  2000      *

  2001      * If the initial date/time is outside the bounds specified by the

  2002      * minimum and maximum, it is set to the nearest valid setting.

  2003      *

  2004      * A panic will occur if the minimum date/time is later than the

  2005      * maximum date/time.

  2006      *

  2007      * @param aMinimumTimeAndDate The minimum date and time value.

  2008      * @param aMaximumTimeAndDate The maximum date and time value.

  2009      * @param aInitialTimeAndDate The initial date and time value.

  2010      * @param aFlags A bitmask of flags. See eikon.hrh file, EEikTime,

  2011      * EEikDate etc.

  2012      * @param aInterveningText Descriptor containing the text to use to

  2013      * separate the time and date portions of the editor.

  2014      */

  2015 	IMPORT_C void ConstructL(const TTime& aMinimumTimeAndDate, const TTime& aMaximumTimeAndDate, const TTime& aInitialTimeAndDate, TUint32 aFlags, HBufC* aInterveningText=NULL);

  2017     /**

  2018      * Sets the values of the time and date editor's fields.

  2019      *

  2020      * @param aTimeAndDate The new value for the date and time editor's

  2021      * fields.

  2022      */

  2023 	IMPORT_C void SetTimeAndDate(const TTime& aTimeAndDate);

  2025     /**

  2026      * Gets the time and date editor's value.

  2027      *

  2028      * @return The editor's value.

  2029      */

  2030 	IMPORT_C TTime TimeAndDate() const;

  2032     /**

  2033      * Sets the uninitialized status of the editor.

  2034      *

  2035      * @param aUninitialised If ETrue, sets the editor as uninitialized,

  2036      *                       i.e. it doesn't display anything.

  2037      */

  2038 	IMPORT_C void SetUninitialised(TBool aUninitialised);

  2040 	/**

  2041 	 * Gets the uninitialized status of the editor.

  2042 	 *

  2043 	 * @return ETrue, if the editor is set as uninitialized.

  2044 	 */

  2045 	IMPORT_C TBool IsUninitialised() const;

  2047 	// from CEikTTimeEditor

  2049     /**

  2050      * Sets the range of allowable values.

  2051      *

  2052      * These define the maximum and minimum time/date values that may be

  2053      * entered by the user.

  2054      *

  2055      * If the existing date/time value is outside the new bounds, it is

  2056      * reset to the nearest allowable value.

  2057      *

  2058      * @param aMinimumTimeAndDate The minimum allowable value.

  2059      * @param aMaximumTimeAndDate The maximum allowable value.

  2060      */

  2061 	IMPORT_C virtual void SetMinimumAndMaximum(const TTime& aMinimumTimeAndDate, const TTime& aMaximumTimeAndDate); // only values inside the initial minimum and maximum are permitted

  2063     /**

  2064      * Gets the range of allowable values that may be entered by the user.

  2065      *

  2066      * @param aMinimumTimeAndDate On return, contains the time and date

  2067      * editor's minimum allowable value.

  2068      * @param aMaximumTimeAndDate On return, contains the time and date

  2069      * editor's maximum allowable value.

  2070      */

  2071 	IMPORT_C virtual void GetMinimumAndMaximum(TTime& aMinimumTimeAndDate, TTime& aMaximumTimeAndDate) const;

  2073 	// from CCoeControl

  2075     /**

  2076      * Handles key events.

  2077      *

  2078      * For example, the Tab key validates and launches a calendar popout.

  2079      *

  2080      * Calls CEikMfne::OfferKeyEventL() if the control does not consume the

  2081      * key.

  2082      *

  2083      * @param aKeyEvent The key event.

  2084      * @param aType The type of key event.

  2085      * @return Returns EKeyWasConsumed if the control consumes the key.

  2086      */

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

  2089     /**

  2090      * Second phase construction from a resource.

  2091      *

  2092      * This function completes the construction of a newly-allocated

  2093      * date/time editor from a TIME_AND_DATE_EDITOR resource. The minimum and

  2094      * maximum date/times, the date and time flag settings, and the intervening

  2095      * text are read from the resource, and ConstructL() is called with these

  2096      * settings. The initial date/time is set to the maximum date/time value.

  2097      *

  2098      * @param aResourceReader A resource file reader.

  2099      */

  2100 	IMPORT_C virtual void ConstructFromResourceL(TResourceReader& aResourceReader);

  2102     /**

  2103      * Prepares the editor for focus loss.

  2104      *

  2105      * This function should be called to validate the editor's contents

  2106      * when an attempt is made to remove focus from the control. If the control

  2107      * value is not within the bounds specified by the minimum and maximum

  2108      * date/time values, it is reset to the nearest allowable value, the

  2109      * function will leave and display an appropriate message.

  2110      */

  2111 	IMPORT_C virtual void PrepareForFocusLossL();

  2113     /**

  2114      * From @c CCoeControl.

  2115      *

  2116      * Handles pointer events.

  2117      *

  2118      * @param aPointerEvent The pointer event.

  2119      */

  2120     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  2122 private:

  2123 	// from CEikMfne

  2124 	virtual void CreatePopoutIfRequiredL();

  2125 	IMPORT_C virtual void CEikMfne_Reserved();

  2126 	// from CEikTTimeEditor

  2127 	virtual void SetTTime(const TTime& aTimeAndDate);

  2128 	virtual TTime GetTTime() const; // can only be called if PrepareForFocusLossL() succeeded

  2129 private:

  2130 	// from MEikCalendarDialogObserver

  2131 	virtual void GetMinimumAndMaximumAndInitialDatesForCalendarL(TTime& aMinimumDate, TTime& aMaximumDate, TTime& aInitialDate) const;

  2132 	virtual void SetDateFromCalendarAndDrawNow(const TTime& aDate);

  2133 	// miscellaneous functions

  2134 	void DoSetMinimumAndMaximum(const TTime& aMinimumTimeAndDate, const TTime& aMaximumTimeAndDate);

  2135 private:

  2136     /**

  2137     * From CAknControl

  2138     */

  2139     IMPORT_C void* ExtensionInterface( TUid aInterface );

  2140 private:

  2141 	CTimeEditor* iTimeEditor;

  2142 	CDateEditor* iDateEditor;

  2143 	TTime iMinimumTimeAndDate;

  2144 	TTime iMaximumTimeAndDate;

  2145 	TInt iSpare;

  2146 	};

  2149 //

  2151 /**

  2152  * Duration editor.

  2153  *

  2154  * The duration editor allows a time duration to be displayed and

  2155  * edited. The editor has a clock icon and an edit field with separators for

  2156  * hours, minutes, and seconds. These fields can all be suppressed using

  2157  * the appropriate flags in the resource declaration.

  2158  *

  2159  * Unlike the time editor control, the duration editor has no am or pm

  2160  * text. This is because the duration is a length of time (from 0 to 24

  2161  * hours), rather than a point in time.

  2162  *

  2163  * The minimum and maximum values are set, and values outside these

  2164  * limits are invalid.

  2165  *

  2166  * The editor has an associated resource struct DURATION_EDITOR and

  2167  * control factory identifier EEikCtDurationEditor.

  2168  */

  2169 class CEikDurationEditor : public CEikMfne

  2170 	{

  2171 public:

  2172 	// miscellaneous functions

  2174     /**

  2175      * Default constructor.

  2176      *

  2177      * This function should be used as the first stage in two stage

  2178      * construction, followed by a call to either ConstructFromResourceL() to

  2179      * initialise the editor's field values from a resource file, or ConstructL()

  2180      * if no resource file is used.

  2181      */

  2182 	IMPORT_C CEikDurationEditor();

  2184     /**

  2185      * Destructor.

  2186      *

  2187      * The destructor frees the resources owned by the duration editor,

  2188      * prior to its destruction.

  2189      */

  2190 	IMPORT_C virtual ~CEikDurationEditor();

  2192     /**

  2193      * Second phase construction.

  2194      *

  2195      * This function completes the construction of a newly-allocated

  2196      * duration editor. This function should be used instead of

  2197      * ConstructFromResourceL() when not initialising from a resource file.

  2198      *

  2199      * The function sets the editor's minimum, maximum and initial values.

  2200      * The time separator characters specified in class TLocale are honoured.

  2201      * If the initial duration is less than the minimum value the minimum

  2202      * value is used as the initial setting. If the initial duration is greater

  2203      * than the maximum value the maximum value is used as the initial

  2204      * setting.

  2205      *

  2206      * The aFlags parameter is used to determine whether the seconds or

  2207      * hours fields are not required. The minutes field is always present.

  2208      * Regardless of the value specified in aFlags, 24 hour time format is set,

  2209      * overriding the locale's setting.

  2210      *

  2211      * @param aMinimumDuration The minimum interval in seconds.

  2212      * @param aMaximumDuration The maximum interval in seconds.

  2213      * @param aInitialDuration The initial interval in seconds.

  2214      * @param aFlags Duration editor flags.

  2215      */

  2216 	IMPORT_C void ConstructL(const TTimeIntervalSeconds& aMinimumDuration, const TTimeIntervalSeconds& aMaximumDuration, const TTimeIntervalSeconds& aInitialDuration, TUint32 aFlags);

  2218     /**

  2219      * Sets the minimum and maximum duration values.

  2220      *

  2221      * The user can only enter values between these bounds.

  2222      *

  2223      * @param aMinimumDuration The minimum duration.

  2224      * @param aMaximumDuration The maximum duration.

  2225      * @panic 48 If the minimum duration exceeds the maximum.

  2226      */

  2227 	IMPORT_C void SetMinimumAndMaximum(const TTimeIntervalSeconds& aMinimumDuration, const TTimeIntervalSeconds& aMaximumDuration); // only values inside the initial minimum and maximum are permitted

  2229     /**

  2230      * Gets the duration editor's minimum and maximum values.

  2231      *

  2232      * @param aMinimumDuration On return, the minimum value.

  2233      * @param aMaximumDuration On return, the maximum value.

  2234      */

  2235 	IMPORT_C void GetMinimumAndMaximum(TTimeIntervalSeconds& aMinimumDuration, TTimeIntervalSeconds& aMaximumDuration) const;

  2237     /**

  2238      * Sets the duration editor's value.

  2239      *

  2240      * @param aDuration The new value to convert into hours, minutes and

  2241      * seconds and to which the duration editor's fields will be set.

  2242      */

  2243 	IMPORT_C void SetDuration(const TTimeIntervalSeconds& aDuration);

  2245     /**

  2246      * Gets the duration editor's value and returns it as a period of

  2247      * seconds.

  2248      *

  2249      * @return The editor's value in seconds.

  2250      */

  2251 	IMPORT_C TTimeIntervalSeconds Duration() const; // can only be called if PrepareForFocusLossL() succeeded

  2253 	// framework

  2255     /**

  2256      * Second-phase construction from a resource.

  2257      *

  2258      * The function reads the maximum and minimum duration values, and the

  2259      * flags settings, from a DURATION_EDITOR resource. It sets the initial

  2260      * duration to be the same as the maximum value and honours the locale's

  2261      * time separators.

  2262      *

  2263      * @param aResourceReader A resource file reader.

  2264      */

  2265 	IMPORT_C void ConstructFromResourceL(TResourceReader& aResourceReader);

  2267     /**

  2268      * Editor validation.

  2269      *

  2270      * This function should be called when an attempt is made to remove

  2271      * focus from a duration editor. If the editor value is not within the

  2272      * bounds specified by the minimum and maximum duration values, it is reset to

  2273      * the nearest allowable value - the function will leave.

  2274      */

  2275 	IMPORT_C void PrepareForFocusLossL();

  2277     // From CCoeControl

  2278     /**

  2279      * From @c CCoeControl.

  2280      *

  2281      * Handles pointer events.

  2282      *

  2283      * @param aPointerEvent The pointer event.

  2284      */

  2285     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  2286 private:

  2287 	// miscellaneous functions

  2288 	void DoSetMinimumAndMaximum(const TTimeIntervalSeconds& aMinimumDuration, const TTimeIntervalSeconds& aMaximumDuration);

  2289 	IMPORT_C virtual void CEikMfne_Reserved();

  2290 private:

  2291     /**

  2292     * From CAknControl

  2293     */

  2294     IMPORT_C void* ExtensionInterface( TUid aInterface );

  2295 private:

  2296 	CTimeEditor* iTimeEditor;

  2297 	TTimeIntervalSeconds iMinimumDuration;

  2298 	TTimeIntervalSeconds iMaximumDuration;

  2299 	TInt iSpare;

  2300 	};

  2302 /**

  2303  * Time offset editor.

  2304  *

  2305  * This control allows a signed time offset to be displayed and edited.

  2306  * It has the same fields as the time editor control CEikTimeEditor,

  2307  * except there is no AM or PM text because the value is a time offset,

  2308  * positive or negative, from 0 to 24 hours rather than a point in time.

  2309  *

  2310  * The editor has an associated resource struct TIME_OFFSET_EDITOR and

  2311  * control factory identifier EEikCtTimeOffsetEditor.

  2312  */

  2313 class CEikTimeOffsetEditor : public CEikMfne

  2314 	{

  2315 public:

  2316 	// miscellaneous functions

  2318     /**

  2319      * Default constructor.

  2320      *

  2321      * This function should be used as the first stage in two stage

  2322      * construction, followed by a call to either ConstructFromResourceL() to

  2323      * initialise the editor's field values from a resource file, or ConstructL()

  2324      * if no resource file is used.

  2325      */

  2326 	IMPORT_C CEikTimeOffsetEditor();

  2328     /**

  2329      * Destructor. This frees the resources owned by the time offset editor,

  2330      * prior to its destruction.

  2331      */

  2332 	IMPORT_C virtual ~CEikTimeOffsetEditor();

  2334     /**

  2335      * Second phase constructor.

  2336      *

  2337      * This function completes the construction of a time offset editor, by

  2338      * setting its minimum, maximum and initial values. The time separator

  2339      * characters specified in the system's locale are honoured. It should be

  2340      * called by the container only if the control is not constructed from a

  2341      * resource file.

  2342      *

  2343      * The aFlags parameter is used to determine whether the seconds or

  2344      * hours fields are displayed by the editor. The minutes field is always

  2345      * displayed. This function forces 24 hour time format for the time offset

  2346      * editor, overriding the locale's setting.

  2347      *

  2348      * If the initial time offset is outside the bounds specified, it is

  2349      * invalid and will be reset to the upper or lower bound.

  2350      *

  2351      * The minimum value for a time offset editor is -23:59:59, and the

  2352      * maximum value is 23:59:59.

  2353      *

  2354      * @param aMinimumTimeOffset The minimum allowable value, in seconds.

  2355      * @param aMaximumTimeOffset The maximum allowable value, in seconds.

  2356      * @param aInitialTimeOffset The initial value, in seconds.

  2357      * @param aFlags Determines which fields are required. Specify

  2358      * CTimeEditor::EWithoutSecondsField for no seconds field,

  2359      * CTimeEditor::EWithoutHoursField for no hours field. 24 hour clock format is set, regardless

  2360      * of the flag setting specified in this parameter.

  2361      */

  2362 	IMPORT_C void ConstructL(const TTimeIntervalSeconds& aMinimumTimeOffset, const TTimeIntervalSeconds& aMaximumTimeOffset, const TTimeIntervalSeconds& aInitialTimeOffset, TUint32 aFlags);

  2364     /**

  2365      * Sets the range of allowable offset values.

  2366      *

  2367      * These define the maximum and minimum values that may be entered by

  2368      * the user.

  2369      *

  2370      * If the existing offset value is outside the bounds set by this

  2371      * function, it is reset to the nearest boundary value.

  2372      *

  2373      * @param aMinimumTimeOffset The minimum allowable value.

  2374      * @param aMaximumTimeOffset The maximum allowable value.

  2375      * @panic 49 If the minimum exceeds the maximum.

  2376      */

  2377 	IMPORT_C void SetMinimumAndMaximum(const TTimeIntervalSeconds& aMinimumTimeOffset, const TTimeIntervalSeconds& aMaximumTimeOffset); // only values inside the initial minimum and maximum are permitted

  2379     /**

  2380      * Gets the range of allowable values that may be entered by the user.

  2381      *

  2382      * @param aMinimumTimeOffset On return, contains the time offset

  2383      * editor’s minimum allowable value.

  2384      * @param aMaximumTimeOffset On return, contains the time offset

  2385      * editor’s maximum allowable value.

  2386      */

  2387 	IMPORT_C void GetMinimumAndMaximum(TTimeIntervalSeconds& aMinimumTimeOffset, TTimeIntervalSeconds& aMaximumTimeOffset) const;

  2389     /**

  2390      * Sets the time offset editor's value.

  2391      *

  2392      * The sign is set according to whether the value specified is positive

  2393      * or negative.

  2394      *

  2395      * @param aTimeOffset The new offset value to which to assign to the

  2396      * editor.

  2397      */

  2398 	IMPORT_C void SetTimeOffset(const TTimeIntervalSeconds& aTimeOffset);

  2400     /**

  2401      * Gets the time offset editor's value converted into seconds.

  2402      *

  2403      * @return The editor's value in seconds.

  2404      */

  2405 	IMPORT_C TTimeIntervalSeconds TimeOffset() const; // can only be called if PrepareForFocusLossL() succeeded

  2407 	// framework

  2409     /**

  2410      * Second phase construction from a resource.

  2411      *

  2412      * This function completes the construction of a time offset editor

  2413      * from a TIME_OFFSET_EDITOR resource.

  2414      *

  2415      * The minimum and maximum time offsets, and the flags settings are

  2416      * read from the resource, and ConstructL() is called with these settings.

  2417      * The initial time offset is set to the maximum time offset value.

  2418      *

  2419      * @param aResourceReader A resource file reader.

  2420      */

  2421 	IMPORT_C void ConstructFromResourceL(TResourceReader& aResourceReader);

  2423     /**

  2424      * Prepares editor for focus loss.

  2425      *

  2426      * This function should be called to validate the editor’s contents

  2427      * when an attempt is made to remove focus from the control.

  2428      *

  2429      * If the control value is not within the bounds specified by the

  2430      * minimum and maximum time offset values, it is reset to the nearest

  2431      * allowable value. The function then leaves.

  2432      */

  2433 	IMPORT_C void PrepareForFocusLossL();

  2435     // From CCoeControl

  2437     /**

  2438      * From @c CCoeControl.

  2439      *

  2440      * Handles pointer events.

  2441      *

  2442      * @param aPointerEvent The pointer event.

  2443      */

  2444     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

  2446 private:

  2447 	// miscellaneous functions

  2448 	void DoSetMinimumAndMaximum(const TTimeIntervalSeconds& aMinimumTimeOffset, const TTimeIntervalSeconds& aMaximumTimeOffset);

  2449 	IMPORT_C virtual void CEikMfne_Reserved();

  2450 private:

  2451     /**

  2452     * From CAknControl

  2453     */

  2454     IMPORT_C void* ExtensionInterface( TUid aInterface );

  2455 private:

  2456 	CTimeEditor* iTimeEditor;

  2457 	TTimeIntervalSeconds iMinimumTimeOffset;

  2458 	TTimeIntervalSeconds iMaximumTimeOffset;

  2459 	// none of these pointers owns anything

  2460 	CEikMfneSymbol* iSign;

  2461 	TInt iSpare;

  2462 	};

  2465 //

  2466 // Longitude and Latitude editors removed 2.4.2002:

  2468 enum

  2469 	{

  2470 	EEikOrientationNorthSouth   =0x1000,

  2471 	EEikOrientationWestEast     =0x2000,

  2472 	EEikOrientationMask=EEikOrientationNorthSouth|EEikOrientationWestEast

  2473 	};

  2476 enum

  2477 	{

  2478 	EEikDirectionNegative,

  2479 	EEikDirectionPositive,

  2480 	EEikDirectionMask=EEikDirectionNegative|EEikDirectionPositive

  2481 	};

  2484 enum TEikCompass

  2485 	{

  2486 	EEikCompassNorth=EEikOrientationNorthSouth|EEikDirectionNegative,

  2487 	EEikCompassSouth=EEikOrientationNorthSouth|EEikDirectionPositive,

  2488 	EEikCompassEast=EEikOrientationWestEast|EEikDirectionNegative,

  2489 	EEikCompassWest=EEikOrientationWestEast|EEikDirectionPositive

  2490 	};

  2493 struct SEikDegreesMinutesDirection

  2494 	{

  2495 	TInt iDegrees;

  2496 	TInt iMinutes;

  2497 	TInt iSeconds;

  2498 	TEikCompass iDirection;

  2499 	};

  2501 #endif  // __EIKMFNE_H__

  2502 // End of file

author	William Roberts <williamr@symbian.org>
	Tue, 16 Mar 2010 16:12:26 +0000
branch	Symbian2
changeset 2	2fe1408b6811
parent 1	666f914201fb
child 4	837f303aceeb
permissions	-rw-r--r--