/*

* Copyright (c) 2005-2009 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:  Preview popup controller.

*

*/

#ifndef AKNPREVIEWPOPUPCONTROLLER_H

#define AKNPREVIEWPOPUPCONTROLLER_H

// INCLUDES

#include <e32base.h>

#include <e32std.h>

#include <coecntrl.h>

#include <aknpreviewpopupobserver.h>

// FORWARD DECLARATIONS

class MAknPreviewPopUpContentProvider;

class CAknPreviewPopUp;

// CLASS DECLARATION

/**

*  Class for controlling the preview popup component.

*  Preview popup is a popup that can be used to show some extra information

*  about e.g. a highlighted list item. It cannot get keyboard focus. Popup is

*  shown after a default timeout of one second and hidden on key press or when

*  it has been visible for ten seconds. These timeouts can be changed via this

*  API.

*

*  Preview popup itself provides only timing services and an empty popup window

*  whose frames and background are drawn with the current skin. It is client

*  application's responsibility to provide the actual content. This can be any

*  object derived from CCoeControl. When the popup is shown it asks content's

*  size using CCoeControl::MinimumSize and sizes itself so that the whole

*  content fits into the popup. Content can also be created asynchronously if

*  it takes considerable amount of time.

*

*  @lib avkon.lib

*  @since S60 3.2

*/

NONSHARABLE_CLASS( CAknPreviewPopUpController ) : public CTimer

    {

    public: // Type definitions

        enum TAknPreviewStyle

            {

            ELayoutDefault = 0x0001, // default graphics are used

            ELayoutSubMenu = 0x0002, // submenu graphics are used

            EPermanentMode = 0x0004, // popup stays visible infinitely

            EFixedMode     = 0x0008, // fixed position and size are used

            EExcludeFrames = 0x0010, // frames and heading area are excluded in fixed mode

            EAutoMirror    = 0x0020, // opening direction is automatically mirrored in left-to-right layouts

            EDontClose     = 0x0040  // popup not closed when pointer up received outside popup 

    };

        enum TAknPreviewPopUpContentSize

            {

            ESmall,

            ELarge

            };

    public: // Constructors and destructor

        /**

        * Two-phased constructor. This version should be used if the content

        * is created asynchronously.

        * @param aContent Reference to the content of the preview popup.

        * @param aContentProvider Reference to the content provider of the popup.

        */

        IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,

            MAknPreviewPopUpContentProvider& aContentProvider );

        /**

        * Two-phased constructor. This version should be used if the content is

        * created synchronously i.e. it's ready when the popup is about to be

        * shown. This is also the normal use case.

        * @param aContent Reference to the content of the preview popup.

        */

        IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent );

        /**

        * Two-phased constructor. This version should be used if the content

        * is created asynchronously.

        * @param aContent Reference to the content of the preview popup.

        * @param aContentProvider Reference to the content provider of the popup.

        * @param aStyle Defines the used layout and behavior flags.

        */

        IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,

            MAknPreviewPopUpContentProvider& aContentProvider,

            const TInt aStyle );

        /**

        * Two-phased constructor. This version should be used if the content is

        * created synchronously i.e. it's ready when the popup is about to be

        * shown. This is also the normal use case.

        * @param aContent Reference to the content of the preview popup.

        * @param aStyle Defines the used layout and behavior flags.

        */

        IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,

            const TInt aStyle );

  	    /**

        * Destructor.

        */

        ~CAknPreviewPopUpController();

    public: // New functions

        /**

        * This static function can be used to query the logical size of the

        * screen when drawing the content of the popup. When ELarge is returned

        * more detailed information (e.g. a picture) can be shown whereas ESmall

        * suggests that the available screen area is more limited and simpler

        * content should be used.

        * @return Logical size of the screen.

        */

        IMPORT_C static TAknPreviewPopUpContentSize ContentSizeInLayout();

        /**

        * Sets the delay used before showing the preview popup. The default 

        * delay is one second.

        * @param aDelay Delay in microseconds.

        */

        IMPORT_C void SetPopUpShowDelay( const TTimeIntervalMicroSeconds32& aDelay );

        /**

        * Sets the delay used before hiding the preview popup. The default

        * delay is three seconds.

        * @param aDelay Delay in microseconds.

        */

        IMPORT_C void SetPopUpHideDelay( const TTimeIntervalMicroSeconds32& aDelay );

        /**

        * Sets the preview popup visible after specified delay. If the popup

        * is already visible it is hidden immediately and shown again after the

        * showing delay. Popup is automatically hidden after its hiding delay

        * unless the delay is zero in which case the popup is shown infinitely.

        */

        IMPORT_C void ShowPopUp();

        /**

        * Hides the popup immediately.

        */

        IMPORT_C void HidePopUp();

        /**

        * If application wishes to build preview popup's content asynchronously

        * the content class should be derived from MAknPreviewPopUpContentProvider

        * in addition to CCoeControl. This function must be called by the content

        * object when it has finished its asynchronous building operation.

        */

        IMPORT_C void ContentReady();

        /**

        * Sets the position of preview popup. Popup's size is determined by the

        * size of its content. The popup is placed left and down from the given 

        * point. If fixed mode is used then this function has no effect.

        * @param aPoint Popup's position.

        */

        IMPORT_C void SetPosition( const TPoint& aPoint );

        /**

        * Sets the position of the preview popup 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 popup that follows lists/grids item highlight.

        * @param aHighlightRect Screen-relative rectangle used to calculate 

        * popup's position.

        */

        IMPORT_C void SetPositionByHighlight( const TRect& aHighlightRect );

        /**

        * Adds the observer to the list of observers. Observers in the list are

        * notified of events in preview popup.

        * @param aObserver Observer.

        */

        IMPORT_C void AddObserverL( const MAknPreviewPopUpObserver& aObserver );

        /**

        * Removes the given observer from the observer list.

        * @param aObserver Observer.

        */

        IMPORT_C void RemoveObserver( const MAknPreviewPopUpObserver& aObserver );

        /**

        * Updates popup's size to reflect a change in content's size.

        * Should be called if the size of the content is changed dynamically.

        */

        IMPORT_C void UpdateContentSize();

        /**

        * Returns the popup's size.

        */

        IMPORT_C TSize Size() const;

        /**

        * Sets optional heading text. If heading text is already set the

        * current text is replaced. When set also a closing icon is shown if 

        * the currently active layout supports stylus.

        * @param aText Heading text.

        */

        IMPORT_C void SetHeadingTextL( const TDesC& aText );

        /**

        * Notifies observers about the specified preview popup event.

        * @param aEvent Preview popup event.

        */

        void NotifyObservers( MAknPreviewPopUpObserver::TPreviewPopUpEvent aEvent );

      	/**

      	 * Resets the popup timeout.

      	 */

      	IMPORT_C void ResetTimer();

    protected: // Functions from base classes

	    /**

	    * From CTimer. Cancels an outstanding asynchronous request.

	    */

        void DoCancel();

        /**

        * From CActive. Handles active object's request completion event.

        */

        void RunL();

        /**

        * From CActive. Handles leaves that occur while RunL is executed.

        * @param aError Leave code.

        * @return Always KErrNone.

        */

        TInt RunError( TInt aError );

    private: // Constructors

        /**

        * C++ default constructor.

        * @param aContentProvider Pointer to the content provider of the popup.

        */   

        CAknPreviewPopUpController( 

            MAknPreviewPopUpContentProvider* aContentProvider );

      	/**

      	* Symbian 2nd phase constructor.

      	* @param aContent Reference to the content of the preview popup.

      	* @param aStyle Defines the layout and style of the preview popup.

      	*/

        void ConstructL( CCoeControl& aContent, 

                         const TInt aStyle );

    private: // Data

  	    enum TPreviewState

  	        {

  	        EShowing,

  	        EHiding,

  	        EBuildingContent

  	        };

        // state of preview popup controller

        TPreviewState iState;

  	    // interface for asynchronous content building

        MAknPreviewPopUpContentProvider* iContentProvider; // Not owned

        // pointer to preview popup.

        CAknPreviewPopUp* iPopUp;

        // delay used before showing the preview popup

        TTimeIntervalMicroSeconds32 iPopUpShowDelay;

        // delay used before hiding the preview popup

        TTimeIntervalMicroSeconds32 iPopUpHideDelay;

        // array containing pointers to registered observers

        RPointerArray<MAknPreviewPopUpObserver> iObservers;

        // True if timer is being resetted and the DoCancel should not hide the popup

        TBool iResetting;

    };

#endif // AKNPREVIEWPOPUPCONTROLLER_H

//  End of File