1 aknnotedialog.h

     1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of 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 *     Provides the CAknDialog-derived interface to Avkon Notes.

    16 *

    17 */

    18 

    19 

    20 #ifndef __AKNNOTEDIALOG__

    21 #define __AKNNOTEDIALOG__

    22 

    23 #include <eikdialg.h>

    24 #include "avkon.hrh"

    25 class CEikImage;

    26 class CAknKeySoundSystem;

    27 class CAknNoteControl;

    28 class CAknNoteAttributes;

    29 class CAknNoteDialogExtension;

    30 

    31 

    32 /**

    33  * The note dialog.

    34  *

    35  * Displays a note to the user for: <UL> <LI> Giving notifications. </LI>

    36  * <LI> Asking questions. </LI> <LI> Showing progress. </LI> </UL>

    37  *

    38  * @see CAknNoteControl, CAknNoteAttributes, CAknText

    39  */

    40 class CAknNoteDialog : public CEikDialog

    41 {

    42 

    43 public:

    44 

    45     /**

    46      * The timeout in microseconds for automatically deleting the dialog.

    47      */

    48     enum TTimeout {

    49 

    50         /** 

    51          * Deprecated (not used).

    52          * 

    53          * @deprecated

    54          */

    55     EUndefinedTimeout = 0,   

    56     /// No timeout  

    57     ENoTimeout = 0,         

    58     /// 1.5 seconds 

    59     EShortTimeout = 1500000,

    60     /// 3 seconds

    61     ELongTimeout = 3000000,

    62     /// 0.5 second

    63     EShortestTimeout = 500000   

    64     };

    65 

    66     /**

    67     * The tone played before the dialog is shown.

    68     *

    69     * Application specific tones may be played by casting the application

    70     * defined Sound ID (SID), to @c TTone.

    71     */

    72     enum TTone {

    73 

    74         /** No tone is played. */

    75         ENoTone = 0,		

    76 

    77         /** A confirmation tone is played. */

    78         EConfirmationTone = EAvkonSIDConfirmationTone, 

    79 

    80         /** A warning tone is played. */

    81         EWarningTone = EAvkonSIDWarningTone,      

    82 

    83         /** An error tone is played. */

    84         EErrorTone = EAvkonSIDErrorTone         

    85     };

    86 

    87 public:

    88 

    89     /**

    90      * C++ default constructor. 

    91      *

    92      * Initialises the tone to @c ENoTone and the timeout to @c ENoTimeout. 

    93      *

    94      * @see @c TTone, @c TTimeout.

    95      */

    96     IMPORT_C CAknNoteDialog();

    97 

    98     /**

    99      * C++ default constructor.

   100      *

   101      * Initialises the tone to @c aTone and the timeout to @c aTimeout. 

   102      *

   103      * @param aTone The tone to be played.

   104      * @param aTimeout The timeout (microseconds). Default is @c ENoTimeout.

   105      * @see @c TTone, @c TTimeout.

   106      */

   107     IMPORT_C CAknNoteDialog(const TTone& aTone, 

   108                             const TTimeout& aTimeout = ENoTimeout);

   109 

   110     /**

   111      * C++ default constructor.

   112      *

   113      * Initialises the tone to @c aTone and the timeout to @c aTimeout. 

   114      * Accepts a pointer to @c CEikDialog*. This must be the address of 

   115      * the dialog pointer. When the dialog deletes itself after a timeout, 

   116      * the address pointed to by this pointer is set to NULL. The dialog must

   117      * not be on the stack, it must be on the heap!

   118      *

   119      * @param aSelfPtr Pointer to the address of the dialog.

   120      * @param aTone = @c ENoTone The tone. 

   121      * @param aTimeout = @c ENoTimeout The timeout (microseconds). 

   122      * @see @c TTone, @c TTimeout.

   123      */

   124     IMPORT_C CAknNoteDialog(CEikDialog** aSelfPtr, 

   125                             const TTone& aTone = ENoTone, 

   126                             const TTimeout& aTimeout = ENoTimeout);

   127 

   128     /**

   129      * Destructor. 

   130      *

   131      * Deletes timer and control attributes. If the self pointer is not null, 

   132      * sets the pointer to point to NULL. 

   133      */

   134     IMPORT_C virtual ~CAknNoteDialog();

   135 

   136     /**

   137      * Sets the dialog timeout. 

   138      *

   139      * @see @c TTimeout.

   140      * @param aTimeout The dialog timeout.

   141      */

   142     IMPORT_C void SetTimeout(const TTimeout& aTimeout);

   143 

   144     /**

   145      * Sets the dialog tone .

   146      *

   147      * @see @c TTone.

   148      * @param aTone The dialog tone.

   149      */

   150     IMPORT_C void SetTone(const TTone& aTone);

   151 

   152     /**

   153      * Enables or disables text wrapping. 

   154      *

   155      * Enables or disables text wrapping depending on the values

   156      * of @c aEnabled (true enables text wrapping). When text wrapping is

   157      * disabled a new line in the note dialog starts only after a newline 

   158      * character in the note text. If a line does not fit into the dialog 

   159      * width it is clipped (the last character is replaced with an 

   160      * ellipsis sign).

   161      *

   162      * This method must be called before @c SetTextL as it only influences 

   163      * the wrapping of text that it is yet to be set via API.

   164      *

   165      * @param aEnabled @c ETrue for enabling text wrapping, @c EFalse for 

   166      *        disabling it.

   167      */

   168     IMPORT_C void SetTextWrapping(TBool aEnabled);

   169 

   170     /**

   171      * Enables or disables all text processing done by the dialog.

   172      * This includes text wrapping, text truncation

   173      * and reordering of bidirectional text.

   174      *

   175      * By default, it is enabled.

   176      *

   177      * If text processing is disabled, lines are broken only at explicit 

   178      * line end characters and they are not truncated, but drawn as long

   179      * as they fit. Also, the dialog does not handle reordering of 

   180      * the bidirectional text.

   181      *

   182      * This method must be called before the text is set.

   183      *

   184      * @param aEnabled Enables or disables all text processing.

   185      */

   186     IMPORT_C void SetTextProcessing(TBool aEnabled);

   187 

   188     /**

   189      * Set the dialog image. 

   190      *

   191      * Change the image in the note control. Override the image which was 

   192      * set in the resource file. The dialog takes ownership of the pointer.

   193      * The note image is the big image or icon which is top right. 

   194      *

   195      * @param aImage Pointer to the new image. 

   196      */

   197     IMPORT_C void SetImageL(CEikImage* aImage);

   198 

   199     /**

   200      * Sets the dialog icon. 

   201      *

   202      * Changes the number type icon in the note control. 

   203      *

   204      * Overrides the icon which was set in the resource file. The dialog takes 

   205      * ownership of the pointer The numbertype icon is the small icon which 

   206      * is bottom left in the note (thumbnail icon). 

   207      * 

   208      * @param aIcon Pointer to the icon.

   209      */

   210     IMPORT_C void SetIconL(CEikImage* aIcon);

   211 

   212     /**

   213      * Sets the number in the dialog text. 

   214      *

   215      * Sets a number in the note text. If the text specified in the resource 

   216      * file or via  @c SetTextL() has a \%d in it, e.g. "You have \%d new 

   217      * messages", this number is inserted at the location specified by \%d.  

   218      *

   219      * @param aNumber The number to be inserted in the text.

   220      */

   221     IMPORT_C void SetTextNumberL(TInt aNumber);

   222 

   223     /**

   224      * Sets the text plurality for the dialog. 

   225      *

   226      * Indicates whether to use plural or singular text. These texts must 

   227      * have been specified in the resource file.

   228      *

   229      * @see @c SetTextNumberL().

   230      * @param isPlural @c ETrue if plural text should be used, 

   231      *        @c EFalse otherwise.

   232      */

   233     IMPORT_C void SetTextPluralityL(const TBool isPlural);

   234 

   235     /**

   236      * Sets the dialog text.

   237      *

   238      * This method can set a formatted text, 

   239      * e.g. "You have 1 new message". It can however set an 

   240      * unformatted text as well, e.g. "You have \%d messages". The plurality of

   241      * the dialog must be previously specified - if not singular 

   242      * plurality is used unless there was no singular text specified in the 

   243      * resource file.

   244      *

   245      * @see @c SetTextNumberL(), @c SetTextPluralityL().

   246      * @param aLabel The note text.

   247      */

   248     IMPORT_C void SetTextL(const TDesC& aLabel);

   249 

   250     /**

   251      * From @c CCoeControl.

   252      * 

   253      * Handles key events. 

   254      *

   255      * Any event which is not a key press is forwarded to 

   256      * @c CEikDialog::OfferKeyEventL.

   257      '

   258      * Short key press dismiss the note by calling @c StaticDeleteL.

   259      *

   260      * @see @c StaticDeleteL(), @c TKeyEvent, @c TEventCode.

   261      * @param aKeyEvent Key event details.

   262      * @param aType Type of event (key down, key press, key release, etc).

   263      * @return Indicates whether or not the key event was used 

   264      *         by this control. @c EKeyWasConsumed if the control takes action

   265      *         on the key event or @c EKeyWasNotConsumed otherwise.

   266      */

   267     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

   268                                          TEventCode aType);

   269 

   270     /**

   271      * From @c CCoeControl.

   272      * 

   273      * Handles a change to the control's resources of type @c aType

   274      * which are shared across the environment, e.g. colors or fonts.

   275      *

   276      * @param aType Target resource type.

   277      */

   278     IMPORT_C void HandleResourceChange(TInt aType);

   279 

   280     /**

   281      * Do layout and draw the note dialog. 

   282      *

   283      * Needed when changing control components (e.g. the text) dynamically. 

   284      * This is needed because the size of the dialog might change 

   285      * (e.g. because of bigger text displayed in more lines, etc.)  

   286      * Set methods call @c LayoutAndDraw() if there is a change that

   287      * might affect the dialog layout (e.g. text becames bigger and hence

   288      * requires an extra line).

   289      *

   290      * Derived classes that implement this kind of methods should call

   291      * @c LayoutAndDraw().

   292      */

   293     IMPORT_C void LayoutAndDraw();

   294 

   295     /**

   296      * From @ CEikDialog. 

   297      *

   298      * Executes a dialog.

   299      *

   300      * Plays a tone (if one was defined) and simulates user activity.

   301      * Forwards call to @c CEikDialog::RunLD().

   302      *

   303      * @return The ID of the button used to dismiss the dialog.

   304      */

   305     IMPORT_C virtual TInt RunLD();

   306 

   307 

   308     /**

   309      * From @c CEikDialog. 

   310      *

   311      * Exits a sleeping dialog without deleting it.

   312      */

   313     IMPORT_C void ExitSleepingDialog();

   314 

   315 protected:

   316 

   317     /**

   318      * From @c CEikDialog. 

   319      *

   320      * Sets the size and the position for the layout. 

   321      *

   322      * The dialog height and width are retrieved from the control  

   323      * (if it exists already).If it does not exist, then default values 

   324      * are used. The client rect is obtained from the application UI. 

   325      * @c AknLayoutUtils::LayoutControl  is then executed using the client

   326      * rect and the note width and height.

   327      * 

   328      * @see @c AknLayoutUtils::LayoutControl().

   329      * @param aSize Not used. 

   330      */

   331     IMPORT_C void SetSizeAndPosition(const TSize& aSize);

   332 

   333     /**

   334      * From @c CEikDialog. 

   335      *

   336      * Performs dynamic operations before the layout. 

   337      *

   338      * Called by the Uikon framework before the dialog layout is executed, this

   339      * method can be overrwritten to perform specific operations.

   340      *

   341      * The following operations are performed:- <UL> <LI> The control attributes

   342      * are transferred to the control. The local control attributes are copied 

   343      * into the real control attributes. The local attributes are then deleted.

   344      * </LI> <LI> If a timeout has been specified the timer is started. The 

   345      * callback is StaticDeleteL. </LI> <LI> </LI> </UL> 

   346      * 

   347      * @see @c CAknNoteAttributes, @c TTimer, @c SetEditableL().

   348      */

   349     IMPORT_C void PreLayoutDynInitL(void);

   350 

   351     /**

   352      * From @c CEikDialog. 

   353      *

   354      * Performs dynamic operations after the layout. 

   355      *

   356      * Called by the Uikon framework after the dialog layout is executed, this

   357      * method can be overrwritten to perform specific operations.

   358      *

   359      * The following operations are performed:- <UL> <LI> @c StartAnimationL()

   360      * is called. </LI> </UL> 

   361      * 

   362      * @see @c CAknNoteControl::StartAnimationL().

   363      */

   364     IMPORT_C void PostLayoutDynInitL();

   365 

   366     /**

   367      * Plays a tone. 

   368      *

   369      * The tone must be previously specified. The sound ID is set 

   370      * depending on the tone type. The tone is played using 

   371      * @c CAknKeySoundSystem::playSound(). Derived classes must call this 

   372      * method if they override @c RunLD() and they wish to play a tone. 

   373      *

   374      * @panic EAknPanicNullPointer

   375      * @see @c TTone, @c CAknKeySoundSystem, @c CAknNoteDialog::RunLD().

   376      */

   377     IMPORT_C void PlayTone();

   378 

   379     /**

   380      * Indicates that there is user activity. 

   381      *

   382      * Resets timers which are monitoring user inactivity. This will disable 

   383      * functionality that checks for user inactivity by listening to 

   384      * these timers.

   385      *

   386      * Derived classes must call this method if they override @c RunLD()

   387      * and they wish to report user activity in order to dismiss applications

   388      * such as the screen saver.

   389      *

   390      * @see @c User::ResetInactivityTime().

   391      */

   392     IMPORT_C void ReportUserActivity() const;

   393 

   394     /**

   395      * Deletes the note dialog.

   396      *

   397      * Called when the timer completes, this method deletes the dialog. A

   398      * @c reinterpret_cast to @c CAknNoteDialog* is performed on aThis. If the

   399      * dialog is not a sleeping note then it is deleted. If it is a sleeping

   400      * dialog then the timer is stopped, @c OkToExitL() is called with 

   401      * @c KErrCancel and @c ExitSleepingDialog is executed. 

   402      * 

   403      * @see @c TTimer, @c OkToExitL(), @c ExitSleepingDialog().

   404      * @param aThis Pointer to the dialog.

   405      * @return Always returns @c EFalse.

   406      */

   407     IMPORT_C static TInt StaticDeleteL(TAny* aThis);

   408 

   409     /**

   410      * Gets the control attributes.

   411      *

   412      * If the control has already been created this method return the 

   413      * attributes stored inside the control. If not then the local 

   414      * attributes are returned. The local attributes are transferred to the 

   415      * control in @c PreLayoutDynInitL().

   416      *

   417      * Derived classes should use this method when trying to access the control

   418      * attributes.

   419      * 

   420      * @return Control attributes.

   421      */

   422     IMPORT_C CAknNoteAttributes* ControlAttributes();

   423 

   424     /**

   425      * Transfers the control attributes from the dialog to the control.

   426      *

   427      * Must be called by derived classes in @c PreLayoutDynInitL()

   428      * if this method is not called then the set of API methods that were

   429      * invoked before the control is created will not work.

   430      */

   431     IMPORT_C void TransferControlAttributes();

   432 

   433     /**

   434      * Gets the used sound system.

   435      *

   436      * Calls @c iEikonEnv->AppUi()->KeySounds() and returns the pointer 

   437      * returned by the called method. If there is no application UI 

   438      * return @c NULL. 

   439      *

   440      * @see @c CAknKeySoundSystem, @c CAknAppUi.

   441      * @return Pointer to the used @c CAknKeySoundSystem or @c NULL.

   442      * @panic EAknPanicNullPointer

   443      */

   444     IMPORT_C CAknKeySoundSystem* SoundSystem() const;

   445 

   446     /**

   447      * Gets the Note control. 

   448      *

   449      * Returns the first control on the active page, which is of type

   450      * @c CAknNoteControl. If no control is found (usually because the 

   451      * control has not been created yet) then this method returns @c NULL.

   452      *

   453      * Derived classes must use this method to get access to the note

   454      * control.

   455      *

   456      * @return Pointer to the note control or @c NULL.

   457      */

   458     IMPORT_C CAknNoteControl* NoteControl();

   459 

   460 private:

   461     

   462     void DbgCheckSelfPtr(CEikDialog** aSelfPtr);

   463 

   464 protected:

   465 

   466     /**

   467      * Note timeout timer.

   468      */ 

   469     CPeriodic*          iTimer;		

   470 

   471     /** 

   472      * Note timeout in microseconds.

   473      */ 

   474     TInt                iTimeoutInMicroseconds; 

   475 

   476     /**

   477      * Used for notes that are not modal. 

   478      * The calling application has no way of knowing 

   479      * when the note is deleted. 

   480      */

   481     CEikDialog**        iSelfPtr; 

   482 

   483     /**

   484      * The tone to be played. 

   485      */

   486     TTone               iTone;	

   487 

   488     /**

   489      * Note control attributes.

   490      */

   491     CAknNoteAttributes* iControlAttributes;  

   492 

   493 private:

   494 

   495     //TInt iSpare; 

   496     CAknNoteDialogExtension* iNoteExtension;

   497 

   498 public:

   499 

   500     /**

   501      * Set timeout, tone, resource ID and then initialize and launch 

   502      * the dialog. 

   503      * 

   504      * This method is deprecated and should not be used.

   505      * 

   506      * @deprecated

   507      * @param aTimeout Wanted timeout in microseconds.

   508      * @param aTone Alarm tone.

   509      * @param aResourceID The ID of the wanted resource.

   510      * @return Zero, unless it is a waiting dialog. For a waiting dialog,

   511      *         the return value is the ID of the button that closed the dialog,

   512      *         or zero if it was the cancel button (@c EEikBidCancel).

   513      */

   514     IMPORT_C TInt ExecuteDlgLD(const TTimeout aTimeout,

   515                                const TTone aTone,

   516                                TInt aResourceID);

   517 

   518     /**

   519      * Set tone, resource ID and then initialize and launch 

   520      * the dialog. 

   521      * 

   522      * This method is deprecated and should not be used.

   523      * 

   524      * @deprecated

   525      * @param aTone Alarm tone.

   526      * @param aResourceID The ID of the wanted resource.

   527      * @return Zero, unless it is a waiting dialog. For a waiting dialog,

   528      *         the return value is the ID of the button that closed the dialog,

   529      *         or zero if it was the cancel button (@c EEikBidCancel).

   530      */

   531     IMPORT_C TInt ExecuteDlgLD(const TTone aTone,TInt aResourceID);

   532 

   533     /**

   534      * Set note control ID, resource ID and then initialize and launch 

   535      * the dialog. 

   536      * 

   537      * This method is deprecated and should not be used.

   538      * 

   539      * @deprecated

   540      * @param aResourceId The ID of the wanted resource.

   541      * @param aNoteControlId Not used. 

   542      * @return Zero, unless it is a waiting dialog. For a waiting dialog,

   543      *         the return value is the ID of the button that closed the dialog,

   544      *         or zero if it was the cancel button (@c EEikBidCancel).

   545      */

   546     IMPORT_C TInt ExecuteDlgLD(TInt aResourceId, TInt aNoteControlId=0);

   547 

   548     /**

   549      * Set timeout and tone and run the dialog.

   550      *

   551      * This method is deprecated and should not be used.

   552      *

   553      * @deprecated

   554      * @param aTimeout Wanted timeout in microseconds.

   555      * @param aTone Wanted alarm tone.

   556      * @return The ID of the button used to dismiss the dialog.

   557      */

   558     IMPORT_C TInt RunDlgLD(const TTimeout aTimeout,const TTone aTone);

   559 

   560     /**

   561      * Set tone and run the dialog.

   562      *

   563      * This method is deprecated and should not be used.

   564      *

   565      * @deprecated

   566      * @param aTone Wanted alarm tone.

   567      * @return The ID of the button used to dismiss the dialog.

   568      */    

   569     IMPORT_C TInt RunDlgLD(const TTone aTone);

   570 

   571     /**

   572      * Run the dialog.

   573      *

   574      * This method is deprecated and should not be used.

   575      *

   576      * @deprecated

   577      * @return The ID of the button used to dismiss the dialog.

   578      */    IMPORT_C TInt RunDlgLD();

   579 

   580     /**

   581      * Set NoteControlID and run the dialog.

   582      *

   583      * This method is deprecated and should not be used.

   584      *

   585      * @deprecated

   586      * @param aNoteControlId Not used.

   587      * @return The ID of the button used to dismiss the dialog.

   588      */    

   589     IMPORT_C TInt RunDlgLD(TInt aNoteControlId);

   590 

   591     /** 

   592      * Sets a new label for the specified dialog.

   593      *

   594      * This method is deprecated. @c SetTextL() method should be used 

   595      * instead.

   596      *

   597      * @param aControlId Not used.

   598      * @param aLabel The new label.

   599      */ 

   600     IMPORT_C void SetCurrentLabelL(TInt aControlId,const TDesC& aLabel);

   601 

   602 private: 

   603 

   604     IMPORT_C virtual void CEikDialog_Reserved_1();

   605 

   606     IMPORT_C virtual void CEikDialog_Reserved_2();	

   607 

   608 private: // new virtual function.

   609 

   610     IMPORT_C virtual void CAknNoteDialog_Reserved();

   611 

   612 protected:

   613 

   614     // This method id reserved for CEikAlert usage

   615     /** 

   616      * Sets an indication that memory should not be allocated.

   617      * 

   618      * This method is reserved for CEikAlert usage.

   619      */ 

   620     IMPORT_C void SetNoMemoryAllocation();

   621 

   622 

   623 private: // from eikdialog

   624 

   625     IMPORT_C void SizeChanged();

   626 

   627     void SetSkinBackGroundRect(); 

   628 

   629 private:

   630 

   631     void CreateExtensionL();

   632 

   633     static TInt CallbackStartAnimationL(TAny* aThis);

   634 

   635 public:

   636 

   637     /**

   638      * From @c CCoeControl.

   639      *

   640      * Processes the pointer event directed to the dialog.

   641      * 

   642      * @param aPointerEvent The pointer event directed to the notedialog.

   643      */

   644     IMPORT_C virtual void HandlePointerEventL(

   645                                         const TPointerEvent& aPointerEvent);

   646 

   647 private:

   648 

   649     /**

   650     * From @c CAknControl.

   651     */

   652     IMPORT_C void* ExtensionInterface( TUid aInterface );

   653     };

   654 

   655 

   656 #endif  // __AKNNOTEDIALOG__

   657 

   658 // End of file