/*

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

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*     Provides the CAknDialog-derived interface to Avkon Notes.

*

*/

#ifndef __AKNNOTEDIALOG__

#define __AKNNOTEDIALOG__

#include <eikdialg.h>

#include "avkon.hrh"

class CEikImage;

class CAknKeySoundSystem;

class CAknNoteControl;

class CAknNoteAttributes;

class CAknNoteDialogExtension;

/**

 * The note dialog.

 *

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

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

 *

 * @see CAknNoteControl, CAknNoteAttributes, CAknText

 */

class CAknNoteDialog : public CEikDialog

{

public:

    /**

     * The timeout in microseconds for automatically deleting the dialog.

     */

    enum TTimeout {

        /** 

         * Deprecated (not used).

         * 

         * @deprecated

         */

    EUndefinedTimeout = 0,   

    /// No timeout  

    ENoTimeout = 0,         

    /// 1.5 seconds 

    EShortTimeout = 1500000,

    /// 3 seconds

    ELongTimeout = 3000000,

    /// 0.5 second

    EShortestTimeout = 500000   

    };

    /**

    * The tone played before the dialog is shown.

    *

    * Application specific tones may be played by casting the application

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

    */

    enum TTone {

        /** No tone is played. */

        ENoTone = 0,		

        /** A confirmation tone is played. */

        EConfirmationTone = EAvkonSIDConfirmationTone, 

        /** A warning tone is played. */

        EWarningTone = EAvkonSIDWarningTone,      

        /** An error tone is played. */

        EErrorTone = EAvkonSIDErrorTone         

    };

public:

    /**

     * C++ default constructor. 

     *

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

     *

     * @see @c TTone, @c TTimeout.

     */

    IMPORT_C CAknNoteDialog();

    /**

     * C++ default constructor.

     *

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

     *

     * @param aTone The tone to be played.

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

     * @see @c TTone, @c TTimeout.

     */

    IMPORT_C CAknNoteDialog(const TTone& aTone, 

                            const TTimeout& aTimeout = ENoTimeout);

    /**

     * C++ default constructor.

     *

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

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

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

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

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

     *

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

     * @param aTone = @c ENoTone The tone. 

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

     * @see @c TTone, @c TTimeout.

     */

    IMPORT_C CAknNoteDialog(CEikDialog** aSelfPtr, 

                            const TTone& aTone = ENoTone, 

                            const TTimeout& aTimeout = ENoTimeout);

    /**

     * Destructor. 

     *

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

     * sets the pointer to point to NULL. 

     */

    IMPORT_C virtual ~CAknNoteDialog();

    /**

     * Sets the dialog timeout. 

     *

     * @see @c TTimeout.

     * @param aTimeout The dialog timeout.

     */

    IMPORT_C void SetTimeout(const TTimeout& aTimeout);

    /**

     * Sets the dialog tone .

     *

     * @see @c TTone.

     * @param aTone The dialog tone.

     */

    IMPORT_C void SetTone(const TTone& aTone);

    /**

     * Enables or disables text wrapping. 

     *

     * Enables or disables text wrapping depending on the values

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

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

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

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

     * ellipsis sign).

     *

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

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

     *

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

     *        disabling it.

     */

    IMPORT_C void SetTextWrapping(TBool aEnabled);

    /**

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

     * This includes text wrapping, text truncation

     * and reordering of bidirectional text.

     *

     * By default, it is enabled.

     *

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

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

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

     * the bidirectional text.

     *

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

     *

     * @param aEnabled Enables or disables all text processing.

     */

    IMPORT_C void SetTextProcessing(TBool aEnabled);

    /**

     * Set the dialog image. 

     *

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

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

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

     *

     * @param aImage Pointer to the new image. 

     */

    IMPORT_C void SetImageL(CEikImage* aImage);

    /**

     * Sets the dialog icon. 

     *

     * Changes the number type icon in the note control. 

     *

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

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

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

     * 

     * @param aIcon Pointer to the icon.

     */

    IMPORT_C void SetIconL(CEikImage* aIcon);

    /**

     * Sets the number in the dialog text. 

     *

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

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

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

     *

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

     */

    IMPORT_C void SetTextNumberL(TInt aNumber);

    /**

     * Sets the text plurality for the dialog. 

     *

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

     * have been specified in the resource file.

     *

     * @see @c SetTextNumberL().

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

     *        @c EFalse otherwise.

     */

    IMPORT_C void SetTextPluralityL(const TBool isPlural);

    /**

     * Sets the dialog text.

     *

     * This method can set a formatted text, 

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

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

     * the dialog must be previously specified - if not singular 

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

     * resource file.

     *

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

     * @param aLabel The note text.

     */

    IMPORT_C void SetTextL(const TDesC& aLabel);

    /**

     * From @c CCoeControl.

     * 

     * Handles key events. 

     *

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

     * @c CEikDialog::OfferKeyEventL.

     '

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

     *

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

     * @param aKeyEvent Key event details.

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

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

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

     *         on the key event or @c EKeyWasNotConsumed otherwise.

     */

    IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

                                         TEventCode aType);

    /**

     * From @c CCoeControl.

     * 

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

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

     *

     * @param aType Target resource type.

     */

    IMPORT_C void HandleResourceChange(TInt aType);

    /**

     * Do layout and draw the note dialog. 

     *

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

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

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

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

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

     * requires an extra line).

     *

     * Derived classes that implement this kind of methods should call

     * @c LayoutAndDraw().

     */

    IMPORT_C void LayoutAndDraw();

    /**

     * From @ CEikDialog. 

     *

     * Executes a dialog.

     *

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

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

     *

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

     */

    IMPORT_C virtual TInt RunLD();

    /**

     * From @c CEikDialog. 

     *

     * Exits a sleeping dialog without deleting it.

     */

    IMPORT_C void ExitSleepingDialog();

protected:

    /**

     * From @c CEikDialog. 

     *

     * Sets the size and the position for the layout. 

     *

     * The dialog height and width are retrieved from the control  

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

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

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

     * rect and the note width and height.

     * 

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

     * @param aSize Not used. 

     */

    IMPORT_C void SetSizeAndPosition(const TSize& aSize);

    /**

     * From @c CEikDialog. 

     *

     * Performs dynamic operations before the layout. 

     *

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

     * method can be overrwritten to perform specific operations.

     *

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

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

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

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

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

     * 

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

     */

    IMPORT_C void PreLayoutDynInitL(void);

    /**

     * From @c CEikDialog. 

     *

     * Performs dynamic operations after the layout. 

     *

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

     * method can be overrwritten to perform specific operations.

     *

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

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

     * 

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

     */

    IMPORT_C void PostLayoutDynInitL();

    /**

     * Plays a tone. 

     *

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

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

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

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

     *

     * @panic EAknPanicNullPointer

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

     */

    IMPORT_C void PlayTone();

    /**

     * Indicates that there is user activity. 

     *

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

     * functionality that checks for user inactivity by listening to 

     * these timers.

     *

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

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

     * such as the screen saver.

     *

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

     */

    IMPORT_C void ReportUserActivity() const;

    /**

     * Deletes the note dialog.

     *

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

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

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

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

     * @c KErrCancel and @c ExitSleepingDialog is executed. 

     * 

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

     * @param aThis Pointer to the dialog.

     * @return Always returns @c EFalse.

     */

    IMPORT_C static TInt StaticDeleteL(TAny* aThis);

    /**

     * Gets the control attributes.

     *

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

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

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

     * control in @c PreLayoutDynInitL().

     *

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

     * attributes.

     * 

     * @return Control attributes.

     */

    IMPORT_C CAknNoteAttributes* ControlAttributes();

    /**

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

     *

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

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

     * invoked before the control is created will not work.

     */

    IMPORT_C void TransferControlAttributes();

    /**

     * Gets the used sound system.

     *

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

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

     * return @c NULL. 

     *

     * @see @c CAknKeySoundSystem, @c CAknAppUi.

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

     * @panic EAknPanicNullPointer

     */

    IMPORT_C CAknKeySoundSystem* SoundSystem() const;

    /**

     * Gets the Note control. 

     *

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

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

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

     *

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

     * control.

     *

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

     */

    IMPORT_C CAknNoteControl* NoteControl();

private:

    void DbgCheckSelfPtr(CEikDialog** aSelfPtr);

protected:

    /**

     * Note timeout timer.

     */ 

    CPeriodic*          iTimer;		

    /** 

     * Note timeout in microseconds.

     */ 

    TInt                iTimeoutInMicroseconds; 

    /**

     * Used for notes that are not modal. 

     * The calling application has no way of knowing 

     * when the note is deleted. 

     */

    CEikDialog**        iSelfPtr; 

    /**

     * The tone to be played. 

     */

    TTone               iTone;	

    /**

     * Note control attributes.

     */

    CAknNoteAttributes* iControlAttributes;  

private:

    //TInt iSpare; 

    CAknNoteDialogExtension* iNoteExtension;

public:

    /**

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

     * the dialog. 

     * 

     * This method is deprecated and should not be used.

     * 

     * @deprecated

     * @param aTimeout Wanted timeout in microseconds.

     * @param aTone Alarm tone.

     * @param aResourceID The ID of the wanted resource.

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

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

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

     */

    IMPORT_C TInt ExecuteDlgLD(const TTimeout aTimeout,

                               const TTone aTone,

                               TInt aResourceID);

    /**

     * Set tone, resource ID and then initialize and launch 

     * the dialog. 

     * 

     * This method is deprecated and should not be used.

     * 

     * @deprecated

     * @param aTone Alarm tone.

     * @param aResourceID The ID of the wanted resource.

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

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

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