/*

* Copyright (c) 2005, 2006 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* 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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  The interface of the info pop-up note

*

*/

// ------------------------------------------------------------------------

// How to use this info popup component (basic case):

//

//

//  #include <AknInfoPopupNote.h>

//  CAknInfoPopupNoteController* iPopupController;

//  ...

//  iPopupController = CAknInfoPopupNoteController::NewL();

//  ...

//  iPopupController->SetTextL( strTestText );

//  iPopupController->ShowInfoPopupNote();

//  ...

//  delete iPopupController;

// ------------------------------------------------------------------------

#ifndef CAKNINFOPOPUPNOTECONTROLLER_H

#define CAKNINFOPOPUPNOTECONTROLLER_H

//  INCLUDES

#include <e32base.h>

#include <gulalign.h>

#include "avkon.hrh"

// FORWARD DECLARATIONS

class CAknInfoPopupNote;

class CAknInfoPopupNoteController;

// CLASS DECLARATION

/**

 *  Observer class for notifying popup's showing and hiding.

 *

 *  @lib avkon.lib

 *  @since Series 60 3.0

 */

class MAknInfoPopupNoteObserver

    {

    public:

        enum TAknInfoPopupNoteEvent

            {

            EInfoPopupNoteShown,

            EInfoPopupNoteHidden

            };

        /**

        * Handles events reported from info popup note.

        * @param aController The controller that controls the note, from

        *   where the event originates.

        * @param aEvent The event.

        */

        virtual void HandleInfoPopupNoteEvent(

            CAknInfoPopupNoteController* aController,

            TAknInfoPopupNoteEvent aEvent ) = 0;

    };

/**

 *  The controller part of popup.

 *  It is active object, and uses timer to show popup after specified

 *  time interval (default 1 sec.) and popup hides automaticly

 *  after an other period (default 10 sec.).

 *

 *  @lib avkon.lib

 *  @since Series 60 3.0

 */

class CAknInfoPopupNoteController : public CTimer

    {

public:

    /**

     * The tone played before the dialog is shown.

     * Application specific tones may be played by casting the application

     *  defined Sound ID (SID), to 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: // Constructors and destructor

    /**

     * Two-phased constructor.

     */

    IMPORT_C static CAknInfoPopupNoteController* NewL();

    /**

     * Destructor.

     */

    virtual ~CAknInfoPopupNoteController();

public: // New functions

    /**

    * Set time delay period before popup is shown (in milliseconds).

    * (if this isn't set, default delay time before show is 1 sec. )

    * @param aMilliSeconds Wanted delay time in milliseconds.

    */

    IMPORT_C void SetTimeDelayBeforeShow( TInt aMilliSeconds );

    /**

    * Set time period how long popup is in view (in milliseconds).

    * (if this isn't set, default show time is 10 sec. )

    * @param aMilliSeconds Wanted show time in milliseconds.

    * if set to 0, popup is shown until HideInfoPopupNote is called

    */

    IMPORT_C void SetTimePopupInView( TInt aMilliSeconds );

    /**

    * Set text to show in popup. If given text is too long for popup,

    * it is truncated.

    * @param aText Text to show in popup.

    */

    IMPORT_C void SetTextL( const TDesC& aText );

    /**

    * Show popup after delay time (hide possible previous popup immediately)

    * and hide popup again after setted time.

    */

    IMPORT_C void ShowInfoPopupNote();

    /**

    * Hide popup immediately.

    */

    IMPORT_C void HideInfoPopupNote();

    /**

    * Adds an observer for the pop-up.

    * @param aObserver The observer to be added.

    */

    IMPORT_C void AddObserverL( const MAknInfoPopupNoteObserver& aObserver );

    /**

    * Removes an observer from the pop-up.

    * @param aObserver The observer to be removed.

    */

    IMPORT_C void RemoveObserver( const MAknInfoPopupNoteObserver& aObserver );

    /**

    * Sets the position and alignment of the info pop-up note.

    * @since 3.1

    * @param aPosition The position, where pop-up note is displayed.

    * @param aAlignment Specifies the part of pop-up note that will be aligned

    *    with the given position.

    */

    IMPORT_C void SetPositionAndAlignment( const TPoint& aPosition,

                                           const TGulAlignmentValue& aAlignment );

    /**

    * Sets the position of the info pop-up note so that it is aligned with the

    * given rectangle as specified in the LAF data. This is intented to be

    * used in conjunction with lists and grids if the application wishes to

    * implement a pop-up that follows lists/grids item highlight.

    * @since 3.1

    * @param aHighlightRect Screen-relative rectangle used to calculate

    *       pop-up's position.

    */

    IMPORT_C void SetPositionByHighlight( const TRect& aHighlightRect );

    /**

    * Restores the info pop-up note's default position discarding previously

    * set values to position and alignment.

    * @since 3.1

    */

    IMPORT_C void RestoreDefaultPosition();

    /**

    * Sets the tooltip mode. When tooltip mode is on, info pop-up note is

    * displayed with only one line of text, and the width of the pop-up note

    * depends on the text length.

    * @since 3.1

    * @param aTooltipMode ETrue to set tooltip mode on, EFalse to set it off.

    */

    IMPORT_C void SetTooltipModeL( const TBool aTooltipMode );

    /**

    * Notifies the observers of the info popup note of an event.

    * @param aEvent The event, of which the observers are notified.

    */

    void NotifyObservers( MAknInfoPopupNoteObserver::TAknInfoPopupNoteEvent aEvent );

    /**

    * Set the tone to be played when the info popup note is shown

    * @param aTone The tone

    */

    IMPORT_C void SetTone( const TTone& aTone );

    /**

    * Whether info popup note will be automatically hidden 

    * or not when app ui is faded (true by default) 

    * @since 3.1

    * @param aHide ETrue when hidden, EFalse when shown or controlled externally

    */

    IMPORT_C void HideWhenAppFaded( const TBool aHide );

protected:

    /**

	* From CTimer. Cancels an outstanding asynchronous request.

	*/

    void DoCancel();

private: // From CActive

    /**

    * Show popup. Called by system framework.

    */

    void RunL();

private:

    /**

     * C++ default constructor.

     */

    CAknInfoPopupNoteController();

    /**

     * By default Symbian 2nd phase constructor is private.

     */

    void ConstructL();

    /**

    * Play the tone.

    */

    void PlayTone();

private: // Data

    enum TInfoPopupNoteState

        {

        EHidden,

        EWaitingToShow,

        EShowing

        };

    TInfoPopupNoteState iState;

    // Own. View object for popup's model-view-controller

    CAknInfoPopupNote* iPopup;

    // Array containing the observers of popup.

    RPointerArray<MAknInfoPopupNoteObserver> iObservers;

    // Delay before popup show

    TInt iTimeDelayBeforeShow; // in microseconds

    // How long popup is shown

    TInt iTimeInView; // in microseconds

    // Specifies the tone

    TTone iTone;

    };

#endif // CAKNINFOPOPUPNOTECONTROLLER_H

// End of File