williamr@2: /*
williamr@2: * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Preview popup controller.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef AKNPREVIEWPOPUPCONTROLLER_H
williamr@2: #define AKNPREVIEWPOPUPCONTROLLER_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <e32base.h>
williamr@2: #include <e32std.h>
williamr@2: #include <coecntrl.h>
williamr@2: #include <aknpreviewpopupobserver.h>
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class MAknPreviewPopUpContentProvider;
williamr@2: class CAknPreviewPopUp;
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: *  Class for controlling the preview popup component.
williamr@2: *  Preview popup is a popup that can be used to show some extra information
williamr@2: *  about e.g. a highlighted list item. It cannot get keyboard focus. Popup is
williamr@2: *  shown after a default timeout of one second and hidden on key press or when
williamr@2: *  it has been visible for ten seconds. These timeouts can be changed via this
williamr@2: *  API.
williamr@2: *
williamr@2: *  Preview popup itself provides only timing services and an empty popup window
williamr@2: *  whose frames and background are drawn with the current skin. It is client
williamr@2: *  application's responsibility to provide the actual content. This can be any
williamr@2: *  object derived from CCoeControl. When the popup is shown it asks content's
williamr@2: *  size using CCoeControl::MinimumSize and sizes itself so that the whole
williamr@2: *  content fits into the popup. Content can also be created asynchronously if
williamr@2: *  it takes considerable amount of time.
williamr@2: *
williamr@2: *  @lib avkon.lib
williamr@2: *  @since S60 3.2
williamr@2: */
williamr@2: NONSHARABLE_CLASS( CAknPreviewPopUpController ) : public CTimer
williamr@2:     {
williamr@2:     public: // Type definitions
williamr@2:         enum TAknPreviewStyle
williamr@2:             {
williamr@2:             ELayoutDefault = 0x0001, // default graphics are used
williamr@2:             ELayoutSubMenu = 0x0002, // submenu graphics are used
williamr@2:             EPermanentMode = 0x0004, // popup stays visible infinitely
williamr@2:             EFixedMode     = 0x0008, // fixed position and size are used
williamr@2:             EExcludeFrames = 0x0010, // frames and heading area are excluded in fixed mode
williamr@2:             EAutoMirror    = 0x0020, // opening direction is automatically mirrored in left-to-right layouts
williamr@2:             EDontClose     = 0x0040  // popup not closed when pointer up received outside popup 
williamr@2:     };
williamr@2:             
williamr@2:         enum TAknPreviewPopUpContentSize
williamr@2:             {
williamr@2:             ESmall,
williamr@2:             ELarge
williamr@2:             };
williamr@2:             
williamr@2:     public: // Constructors and destructor
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor. This version should be used if the content
williamr@2:         * is created asynchronously.
williamr@2:         * @param aContent Reference to the content of the preview popup.
williamr@2:         * @param aContentProvider Reference to the content provider of the popup.
williamr@2:         */
williamr@2:         IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
williamr@2:             MAknPreviewPopUpContentProvider& aContentProvider );
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor. This version should be used if the content is
williamr@2:         * created synchronously i.e. it's ready when the popup is about to be
williamr@2:         * shown. This is also the normal use case.
williamr@2:         * @param aContent Reference to the content of the preview popup.
williamr@2:         */
williamr@2:         IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent );
williamr@2:         
williamr@2:         /**
williamr@2:         * Two-phased constructor. This version should be used if the content
williamr@2:         * is created asynchronously.
williamr@2:         * @param aContent Reference to the content of the preview popup.
williamr@2:         * @param aContentProvider Reference to the content provider of the popup.
williamr@2:         * @param aStyle Defines the used layout and behavior flags.
williamr@2:         */
williamr@2:         IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
williamr@2:             MAknPreviewPopUpContentProvider& aContentProvider,
williamr@2:             const TInt aStyle );
williamr@2: 
williamr@2:         /**
williamr@2:         * Two-phased constructor. This version should be used if the content is
williamr@2:         * created synchronously i.e. it's ready when the popup is about to be
williamr@2:         * shown. This is also the normal use case.
williamr@2:         * @param aContent Reference to the content of the preview popup.
williamr@2:         * @param aStyle Defines the used layout and behavior flags.
williamr@2:         */
williamr@2:         IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
williamr@2:             const TInt aStyle );
williamr@2:             
williamr@2:   	    /**
williamr@2:         * Destructor.
williamr@2:         */
williamr@2:         ~CAknPreviewPopUpController();
williamr@2: 
williamr@2:     public: // New functions
williamr@2:         
williamr@2:         /**
williamr@2:         * This static function can be used to query the logical size of the
williamr@2:         * screen when drawing the content of the popup. When ELarge is returned
williamr@2:         * more detailed information (e.g. a picture) can be shown whereas ESmall
williamr@2:         * suggests that the available screen area is more limited and simpler
williamr@2:         * content should be used.
williamr@2:         * @return Logical size of the screen.
williamr@2:         */
williamr@2:         IMPORT_C static TAknPreviewPopUpContentSize ContentSizeInLayout();
williamr@2: 
williamr@2:         /**
williamr@2:         * Sets the delay used before showing the preview popup. The default 
williamr@2:         * delay is one second.
williamr@2:         * @param aDelay Delay in microseconds.
williamr@2:         */
williamr@2:         IMPORT_C void SetPopUpShowDelay( const TTimeIntervalMicroSeconds32& aDelay );
williamr@2:         
williamr@2:         /**
williamr@2:         * Sets the delay used before hiding the preview popup. The default
williamr@2:         * delay is three seconds.
williamr@2:         * @param aDelay Delay in microseconds.
williamr@2:         */
williamr@2:         IMPORT_C void SetPopUpHideDelay( const TTimeIntervalMicroSeconds32& aDelay );
williamr@2:         
williamr@2:         /**
williamr@2:         * Sets the preview popup visible after specified delay. If the popup
williamr@2:         * is already visible it is hidden immediately and shown again after the
williamr@2:         * showing delay. Popup is automatically hidden after its hiding delay
williamr@2:         * unless the delay is zero in which case the popup is shown infinitely.
williamr@2:         */
williamr@2:         IMPORT_C void ShowPopUp();
williamr@2:         
williamr@2:         /**
williamr@2:         * Hides the popup immediately.
williamr@2:         */
williamr@2:         IMPORT_C void HidePopUp();
williamr@2:         
williamr@2:         /**
williamr@2:         * If application wishes to build preview popup's content asynchronously
williamr@2:         * the content class should be derived from MAknPreviewPopUpContentProvider
williamr@2:         * in addition to CCoeControl. This function must be called by the content
williamr@2:         * object when it has finished its asynchronous building operation.
williamr@2:         */
williamr@2:         IMPORT_C void ContentReady();
williamr@2:         
williamr@2:         /**
williamr@2:         * Sets the position of preview popup. Popup's size is determined by the
williamr@2:         * size of its content. The popup is placed left and down from the given 
williamr@2:         * point. If fixed mode is used then this function has no effect.
williamr@2:         * @param aPoint Popup's position.
williamr@2:         */
williamr@2:         IMPORT_C void SetPosition( const TPoint& aPoint );
williamr@2: 
williamr@2:         /**
williamr@2:         * Sets the position of the preview popup so that it is aligned with the
williamr@2:         * given rectangle as specified in the LAF data. This is intented to be
williamr@2:         * used in conjunction with lists and grids if the application wishes to
williamr@2:         * implement a popup that follows lists/grids item highlight.
williamr@2:         * @param aHighlightRect Screen-relative rectangle used to calculate 
williamr@2:         * popup's position.
williamr@2:         */
williamr@2:         IMPORT_C void SetPositionByHighlight( const TRect& aHighlightRect );
williamr@2: 
williamr@2:         /**
williamr@2:         * Adds the observer to the list of observers. Observers in the list are
williamr@2:         * notified of events in preview popup.
williamr@2:         * @param aObserver Observer.
williamr@2:         */
williamr@2:         IMPORT_C void AddObserverL( const MAknPreviewPopUpObserver& aObserver );
williamr@2:         
williamr@2:         /**
williamr@2:         * Removes the given observer from the observer list.
williamr@2:         * @param aObserver Observer.
williamr@2:         */
williamr@2:         IMPORT_C void RemoveObserver( const MAknPreviewPopUpObserver& aObserver );
williamr@2:         
williamr@2:         /**
williamr@2:         * Updates popup's size to reflect a change in content's size.
williamr@2:         * Should be called if the size of the content is changed dynamically.
williamr@2:         */
williamr@2:         IMPORT_C void UpdateContentSize();
williamr@2:         
williamr@2:         /**
williamr@2:         * Returns the popup's size.
williamr@2:         */
williamr@2:         IMPORT_C TSize Size() const;
williamr@2:         
williamr@2:         /**
williamr@2:         * Sets optional heading text. If heading text is already set the
williamr@2:         * current text is replaced. When set also a closing icon is shown if 
williamr@2:         * the currently active layout supports stylus.
williamr@2:         * @param aText Heading text.
williamr@2:         */
williamr@2:         IMPORT_C void SetHeadingTextL( const TDesC& aText );
williamr@2:         
williamr@2:         /**
williamr@2:         * Notifies observers about the specified preview popup event.
williamr@2:         * @param aEvent Preview popup event.
williamr@2:         */
williamr@2:         void NotifyObservers( MAknPreviewPopUpObserver::TPreviewPopUpEvent aEvent );
williamr@2:       
williamr@2:       	/**
williamr@2:       	 * Resets the popup timeout.
williamr@2:       	 */
williamr@2:       	IMPORT_C void ResetTimer();
williamr@2:       	
williamr@2:     protected: // Functions from base classes
williamr@2: 	
williamr@2: 	    /**
williamr@2: 	    * From CTimer. Cancels an outstanding asynchronous request.
williamr@2: 	    */
williamr@2:         void DoCancel();
williamr@2:         
williamr@2:         /**
williamr@2:         * From CActive. Handles active object's request completion event.
williamr@2:         */
williamr@2:         void RunL();
williamr@2:         
williamr@2:         /**
williamr@2:         * From CActive. Handles leaves that occur while RunL is executed.
williamr@2:         * @param aError Leave code.
williamr@2:         * @return Always KErrNone.
williamr@2:         */
williamr@2:         TInt RunError( TInt aError );
williamr@2: 
williamr@2:     private: // Constructors
williamr@2: 
williamr@2:         /**
williamr@2:         * C++ default constructor.
williamr@2:         * @param aContentProvider Pointer to the content provider of the popup.
williamr@2:         */   
williamr@2:         CAknPreviewPopUpController( 
williamr@2:             MAknPreviewPopUpContentProvider* aContentProvider );
williamr@2: 
williamr@2:       	/**
williamr@2:       	* Symbian 2nd phase constructor.
williamr@2:       	* @param aContent Reference to the content of the preview popup.
williamr@2:       	* @param aStyle Defines the layout and style of the preview popup.
williamr@2:       	*/
williamr@2:         void ConstructL( CCoeControl& aContent, 
williamr@2:                          const TInt aStyle );
williamr@2: 
williamr@2:     private: // Data
williamr@2:   	
williamr@2:   	    enum TPreviewState
williamr@2:   	        {
williamr@2:   	        EShowing,
williamr@2:   	        EHiding,
williamr@2:   	        EBuildingContent
williamr@2:   	        };
williamr@2:   	        
williamr@2:         // state of preview popup controller
williamr@2:         TPreviewState iState;
williamr@2:         
williamr@2:   	    // interface for asynchronous content building
williamr@2:         MAknPreviewPopUpContentProvider* iContentProvider; // Not owned
williamr@2:         
williamr@2:         // pointer to preview popup.
williamr@2:         CAknPreviewPopUp* iPopUp;
williamr@2:         
williamr@2:         // delay used before showing the preview popup
williamr@2:         TTimeIntervalMicroSeconds32 iPopUpShowDelay;
williamr@2:         
williamr@2:         // delay used before hiding the preview popup
williamr@2:         TTimeIntervalMicroSeconds32 iPopUpHideDelay;
williamr@2:         
williamr@2:         // array containing pointers to registered observers
williamr@2:         RPointerArray<MAknPreviewPopUpObserver> iObservers;
williamr@2:         
williamr@2:         // True if timer is being resetted and the DoCancel should not hide the popup
williamr@2:         TBool iResetting;
williamr@2:     };
williamr@2: 
williamr@2: #endif // AKNPREVIEWPOPUPCONTROLLER_H
williamr@2: 
williamr@2: //  End of File