1.1 --- a/epoc32/include/mw/aknpreviewpopupcontroller.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/aknpreviewpopupcontroller.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,295 @@
1.4 -aknpreviewpopupcontroller.h
1.5 +/*
1.6 +* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Preview popup controller.
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef AKNPREVIEWPOPUPCONTROLLER_H
1.24 +#define AKNPREVIEWPOPUPCONTROLLER_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32base.h>
1.28 +#include <e32std.h>
1.29 +#include <coecntrl.h>
1.30 +#include <aknpreviewpopupobserver.h>
1.31 +
1.32 +// FORWARD DECLARATIONS
1.33 +class MAknPreviewPopUpContentProvider;
1.34 +class CAknPreviewPopUp;
1.35 +
1.36 +// CLASS DECLARATION
1.37 +
1.38 +/**
1.39 +* Class for controlling the preview popup component.
1.40 +* Preview popup is a popup that can be used to show some extra information
1.41 +* about e.g. a highlighted list item. It cannot get keyboard focus. Popup is
1.42 +* shown after a default timeout of one second and hidden on key press or when
1.43 +* it has been visible for ten seconds. These timeouts can be changed via this
1.44 +* API.
1.45 +*
1.46 +* Preview popup itself provides only timing services and an empty popup window
1.47 +* whose frames and background are drawn with the current skin. It is client
1.48 +* application's responsibility to provide the actual content. This can be any
1.49 +* object derived from CCoeControl. When the popup is shown it asks content's
1.50 +* size using CCoeControl::MinimumSize and sizes itself so that the whole
1.51 +* content fits into the popup. Content can also be created asynchronously if
1.52 +* it takes considerable amount of time.
1.53 +*
1.54 +* @lib avkon.lib
1.55 +* @since S60 3.2
1.56 +*/
1.57 +NONSHARABLE_CLASS( CAknPreviewPopUpController ) : public CTimer
1.58 + {
1.59 + public: // Type definitions
1.60 + enum TAknPreviewStyle
1.61 + {
1.62 + ELayoutDefault = 0x0001, // default graphics are used
1.63 + ELayoutSubMenu = 0x0002, // submenu graphics are used
1.64 + EPermanentMode = 0x0004, // popup stays visible infinitely
1.65 + EFixedMode = 0x0008, // fixed position and size are used
1.66 + EExcludeFrames = 0x0010, // frames and heading area are excluded in fixed mode
1.67 + EAutoMirror = 0x0020, // opening direction is automatically mirrored in left-to-right layouts
1.68 + EDontClose = 0x0040 // popup not closed when pointer up received outside popup
1.69 + };
1.70 +
1.71 + enum TAknPreviewPopUpContentSize
1.72 + {
1.73 + ESmall,
1.74 + ELarge
1.75 + };
1.76 +
1.77 + public: // Constructors and destructor
1.78 +
1.79 + /**
1.80 + * Two-phased constructor. This version should be used if the content
1.81 + * is created asynchronously.
1.82 + * @param aContent Reference to the content of the preview popup.
1.83 + * @param aContentProvider Reference to the content provider of the popup.
1.84 + */
1.85 + IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
1.86 + MAknPreviewPopUpContentProvider& aContentProvider );
1.87 +
1.88 + /**
1.89 + * Two-phased constructor. This version should be used if the content is
1.90 + * created synchronously i.e. it's ready when the popup is about to be
1.91 + * shown. This is also the normal use case.
1.92 + * @param aContent Reference to the content of the preview popup.
1.93 + */
1.94 + IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent );
1.95 +
1.96 + /**
1.97 + * Two-phased constructor. This version should be used if the content
1.98 + * is created asynchronously.
1.99 + * @param aContent Reference to the content of the preview popup.
1.100 + * @param aContentProvider Reference to the content provider of the popup.
1.101 + * @param aStyle Defines the used layout and behavior flags.
1.102 + */
1.103 + IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
1.104 + MAknPreviewPopUpContentProvider& aContentProvider,
1.105 + const TInt aStyle );
1.106 +
1.107 + /**
1.108 + * Two-phased constructor. This version should be used if the content is
1.109 + * created synchronously i.e. it's ready when the popup is about to be
1.110 + * shown. This is also the normal use case.
1.111 + * @param aContent Reference to the content of the preview popup.
1.112 + * @param aStyle Defines the used layout and behavior flags.
1.113 + */
1.114 + IMPORT_C static CAknPreviewPopUpController* NewL( CCoeControl& aContent,
1.115 + const TInt aStyle );
1.116 +
1.117 + /**
1.118 + * Destructor.
1.119 + */
1.120 + ~CAknPreviewPopUpController();
1.121 +
1.122 + public: // New functions
1.123 +
1.124 + /**
1.125 + * This static function can be used to query the logical size of the
1.126 + * screen when drawing the content of the popup. When ELarge is returned
1.127 + * more detailed information (e.g. a picture) can be shown whereas ESmall
1.128 + * suggests that the available screen area is more limited and simpler
1.129 + * content should be used.
1.130 + * @return Logical size of the screen.
1.131 + */
1.132 + IMPORT_C static TAknPreviewPopUpContentSize ContentSizeInLayout();
1.133 +
1.134 + /**
1.135 + * Sets the delay used before showing the preview popup. The default
1.136 + * delay is one second.
1.137 + * @param aDelay Delay in microseconds.
1.138 + */
1.139 + IMPORT_C void SetPopUpShowDelay( const TTimeIntervalMicroSeconds32& aDelay );
1.140 +
1.141 + /**
1.142 + * Sets the delay used before hiding the preview popup. The default
1.143 + * delay is three seconds.
1.144 + * @param aDelay Delay in microseconds.
1.145 + */
1.146 + IMPORT_C void SetPopUpHideDelay( const TTimeIntervalMicroSeconds32& aDelay );
1.147 +
1.148 + /**
1.149 + * Sets the preview popup visible after specified delay. If the popup
1.150 + * is already visible it is hidden immediately and shown again after the
1.151 + * showing delay. Popup is automatically hidden after its hiding delay
1.152 + * unless the delay is zero in which case the popup is shown infinitely.
1.153 + */
1.154 + IMPORT_C void ShowPopUp();
1.155 +
1.156 + /**
1.157 + * Hides the popup immediately.
1.158 + */
1.159 + IMPORT_C void HidePopUp();
1.160 +
1.161 + /**
1.162 + * If application wishes to build preview popup's content asynchronously
1.163 + * the content class should be derived from MAknPreviewPopUpContentProvider
1.164 + * in addition to CCoeControl. This function must be called by the content
1.165 + * object when it has finished its asynchronous building operation.
1.166 + */
1.167 + IMPORT_C void ContentReady();
1.168 +
1.169 + /**
1.170 + * Sets the position of preview popup. Popup's size is determined by the
1.171 + * size of its content. The popup is placed left and down from the given
1.172 + * point. If fixed mode is used then this function has no effect.
1.173 + * @param aPoint Popup's position.
1.174 + */
1.175 + IMPORT_C void SetPosition( const TPoint& aPoint );
1.176 +
1.177 + /**
1.178 + * Sets the position of the preview popup so that it is aligned with the
1.179 + * given rectangle as specified in the LAF data. This is intented to be
1.180 + * used in conjunction with lists and grids if the application wishes to
1.181 + * implement a popup that follows lists/grids item highlight.
1.182 + * @param aHighlightRect Screen-relative rectangle used to calculate
1.183 + * popup's position.
1.184 + */
1.185 + IMPORT_C void SetPositionByHighlight( const TRect& aHighlightRect );
1.186 +
1.187 + /**
1.188 + * Adds the observer to the list of observers. Observers in the list are
1.189 + * notified of events in preview popup.
1.190 + * @param aObserver Observer.
1.191 + */
1.192 + IMPORT_C void AddObserverL( const MAknPreviewPopUpObserver& aObserver );
1.193 +
1.194 + /**
1.195 + * Removes the given observer from the observer list.
1.196 + * @param aObserver Observer.
1.197 + */
1.198 + IMPORT_C void RemoveObserver( const MAknPreviewPopUpObserver& aObserver );
1.199 +
1.200 + /**
1.201 + * Updates popup's size to reflect a change in content's size.
1.202 + * Should be called if the size of the content is changed dynamically.
1.203 + */
1.204 + IMPORT_C void UpdateContentSize();
1.205 +
1.206 + /**
1.207 + * Returns the popup's size.
1.208 + */
1.209 + IMPORT_C TSize Size() const;
1.210 +
1.211 + /**
1.212 + * Sets optional heading text. If heading text is already set the
1.213 + * current text is replaced. When set also a closing icon is shown if
1.214 + * the currently active layout supports stylus.
1.215 + * @param aText Heading text.
1.216 + */
1.217 + IMPORT_C void SetHeadingTextL( const TDesC& aText );
1.218 +
1.219 + /**
1.220 + * Notifies observers about the specified preview popup event.
1.221 + * @param aEvent Preview popup event.
1.222 + */
1.223 + void NotifyObservers( MAknPreviewPopUpObserver::TPreviewPopUpEvent aEvent );
1.224 +
1.225 + /**
1.226 + * Resets the popup timeout.
1.227 + */
1.228 + IMPORT_C void ResetTimer();
1.229 +
1.230 + protected: // Functions from base classes
1.231 +
1.232 + /**
1.233 + * From CTimer. Cancels an outstanding asynchronous request.
1.234 + */
1.235 + void DoCancel();
1.236 +
1.237 + /**
1.238 + * From CActive. Handles active object's request completion event.
1.239 + */
1.240 + void RunL();
1.241 +
1.242 + /**
1.243 + * From CActive. Handles leaves that occur while RunL is executed.
1.244 + * @param aError Leave code.
1.245 + * @return Always KErrNone.
1.246 + */
1.247 + TInt RunError( TInt aError );
1.248 +
1.249 + private: // Constructors
1.250 +
1.251 + /**
1.252 + * C++ default constructor.
1.253 + * @param aContentProvider Pointer to the content provider of the popup.
1.254 + */
1.255 + CAknPreviewPopUpController(
1.256 + MAknPreviewPopUpContentProvider* aContentProvider );
1.257 +
1.258 + /**
1.259 + * Symbian 2nd phase constructor.
1.260 + * @param aContent Reference to the content of the preview popup.
1.261 + * @param aStyle Defines the layout and style of the preview popup.
1.262 + */
1.263 + void ConstructL( CCoeControl& aContent,
1.264 + const TInt aStyle );
1.265 +
1.266 + private: // Data
1.267 +
1.268 + enum TPreviewState
1.269 + {
1.270 + EShowing,
1.271 + EHiding,
1.272 + EBuildingContent
1.273 + };
1.274 +
1.275 + // state of preview popup controller
1.276 + TPreviewState iState;
1.277 +
1.278 + // interface for asynchronous content building
1.279 + MAknPreviewPopUpContentProvider* iContentProvider; // Not owned
1.280 +
1.281 + // pointer to preview popup.
1.282 + CAknPreviewPopUp* iPopUp;
1.283 +
1.284 + // delay used before showing the preview popup
1.285 + TTimeIntervalMicroSeconds32 iPopUpShowDelay;
1.286 +
1.287 + // delay used before hiding the preview popup
1.288 + TTimeIntervalMicroSeconds32 iPopUpHideDelay;
1.289 +
1.290 + // array containing pointers to registered observers
1.291 + RPointerArray<MAknPreviewPopUpObserver> iObservers;
1.292 +
1.293 + // True if timer is being resetted and the DoCancel should not hide the popup
1.294 + TBool iResetting;
1.295 + };
1.296 +
1.297 +#endif // AKNPREVIEWPOPUPCONTROLLER_H
1.298 +
1.299 +// End of File