1 akninfopopupnotecontroller.h

     1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

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

    15 *

    16 */

    17 

    18 

    19 // ------------------------------------------------------------------------

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

    21 //

    22 //

    23 //  #include <AknInfoPopupNote.h>

    24 //  CAknInfoPopupNoteController* iPopupController;

    25 //  ...

    26 //  iPopupController = CAknInfoPopupNoteController::NewL();

    27 //  ...

    28 //  iPopupController->SetTextL( strTestText );

    29 //  iPopupController->ShowInfoPopupNote();

    30 //  ...

    31 //  delete iPopupController;

    32 // ------------------------------------------------------------------------

    33 

    34 

    35 #ifndef CAKNINFOPOPUPNOTECONTROLLER_H

    36 #define CAKNINFOPOPUPNOTECONTROLLER_H

    37 

    38 //  INCLUDES

    39 #include <e32base.h>

    40 #include <gulalign.h>

    41 #include "avkon.hrh"

    42 

    43 // FORWARD DECLARATIONS

    44 class CAknInfoPopupNote;

    45 class CAknInfoPopupNoteController;

    46 

    47 // CLASS DECLARATION

    48 

    49 /**

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

    51  *

    52  *  @lib avkon.lib

    53  *  @since Series 60 3.0

    54  */

    55 class MAknInfoPopupNoteObserver

    56     {

    57     public:

    58 

    59         enum TAknInfoPopupNoteEvent

    60             {

    61             EInfoPopupNoteShown,

    62             EInfoPopupNoteHidden

    63             };

    64 

    65         /**

    66         * Handles events reported from info popup note.

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

    68         *   where the event originates.

    69         * @param aEvent The event.

    70         */

    71         virtual void HandleInfoPopupNoteEvent(

    72             CAknInfoPopupNoteController* aController,

    73             TAknInfoPopupNoteEvent aEvent ) = 0;

    74     };

    75 

    76 

    77 /**

    78  *  The controller part of popup.

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

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

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

    82  *

    83  *  @lib avkon.lib

    84  *  @since Series 60 3.0

    85  */

    86 class CAknInfoPopupNoteController : public CTimer

    87     {

    88 public:

    89     /**

    90      * The tone played before the dialog is shown.

    91      * Application specific tones may be played by casting the application

    92      *  defined Sound ID (SID), to TTone

    93      */

    94     enum TTone

    95         {

    96         /** No tone is played. */

    97         ENoTone = 0,

    98         /** A confirmation tone is played. */

    99         EConfirmationTone = EAvkonSIDConfirmationTone,

   100         /** A warning tone is played. */

   101         EWarningTone = EAvkonSIDWarningTone,

   102         /** An error tone is played. */

   103         EErrorTone = EAvkonSIDErrorTone

   104         };

   105 

   106 public: // Constructors and destructor

   107 

   108     /**

   109      * Two-phased constructor.

   110      */

   111     IMPORT_C static CAknInfoPopupNoteController* NewL();

   112 

   113     /**

   114      * Destructor.

   115      */

   116     virtual ~CAknInfoPopupNoteController();

   117 

   118 public: // New functions

   119 

   120     /**

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

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

   123     * @param aMilliSeconds Wanted delay time in milliseconds.

   124     */

   125     IMPORT_C void SetTimeDelayBeforeShow( TInt aMilliSeconds );

   126 

   127     /**

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

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

   130     * @param aMilliSeconds Wanted show time in milliseconds.

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

   132     */

   133     IMPORT_C void SetTimePopupInView( TInt aMilliSeconds );

   134 

   135     /**

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

   137     * it is truncated.

   138     * @param aText Text to show in popup.

   139     */

   140     IMPORT_C void SetTextL( const TDesC& aText );

   141 

   142     /**

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

   144     * and hide popup again after setted time.

   145     */

   146     IMPORT_C void ShowInfoPopupNote();

   147 

   148     /**

   149     * Hide popup immediately.

   150     */

   151     IMPORT_C void HideInfoPopupNote();

   152 

   153     /**

   154     * Adds an observer for the pop-up.

   155     * @param aObserver The observer to be added.

   156     */

   157     IMPORT_C void AddObserverL( const MAknInfoPopupNoteObserver& aObserver );

   158 

   159     /**

   160     * Removes an observer from the pop-up.

   161     * @param aObserver The observer to be removed.

   162     */

   163     IMPORT_C void RemoveObserver( const MAknInfoPopupNoteObserver& aObserver );

   164 

   165     /**

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

   167     * @since 3.1

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

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

   170     *    with the given position.

   171     */

   172     IMPORT_C void SetPositionAndAlignment( const TPoint& aPosition,

   173                                            const TGulAlignmentValue& aAlignment );

   174 

   175     /**

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

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

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

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

   180     * @since 3.1

   181     * @param aHighlightRect Screen-relative rectangle used to calculate

   182     *       pop-up's position.

   183     */

   184     IMPORT_C void SetPositionByHighlight( const TRect& aHighlightRect );

   185 

   186     /**

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

   188     * set values to position and alignment.

   189     * @since 3.1

   190     */

   191     IMPORT_C void RestoreDefaultPosition();

   192 

   193     /**

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

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

   196     * depends on the text length.

   197     * @since 3.1

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

   199     */

   200     IMPORT_C void SetTooltipModeL( const TBool aTooltipMode );

   201 

   202     /**

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

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

   205     */

   206     void NotifyObservers( MAknInfoPopupNoteObserver::TAknInfoPopupNoteEvent aEvent );

   207 

   208     /**

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

   210     * @param aTone The tone

   211     */

   212     IMPORT_C void SetTone( const TTone& aTone );

   213 

   214     /**

   215     * Whether info popup note will be automatically hidden 

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

   217     * @since 3.1

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

   219     */

   220     IMPORT_C void HideWhenAppFaded( const TBool aHide );

   221 

   222 protected:

   223 

   224     /**

   225 	* From CTimer. Cancels an outstanding asynchronous request.

   226 	*/

   227     void DoCancel();

   228 

   229 private: // From CActive

   230 

   231     /**

   232     * Show popup. Called by system framework.

   233     */

   234     void RunL();

   235 

   236 private:

   237 

   238     /**

   239      * C++ default constructor.

   240      */

   241     CAknInfoPopupNoteController();

   242 

   243     /**

   244      * By default Symbian 2nd phase constructor is private.

   245      */

   246     void ConstructL();

   247 

   248     /**

   249     * Play the tone.

   250     */

   251     void PlayTone();

   252 

   253 private: // Data

   254 

   255     enum TInfoPopupNoteState

   256         {

   257         EHidden,

   258         EWaitingToShow,

   259         EShowing

   260         };

   261 

   262     TInfoPopupNoteState iState;

   263 

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

   265     CAknInfoPopupNote* iPopup;

   266 

   267     // Array containing the observers of popup.

   268     RPointerArray<MAknInfoPopupNoteObserver> iObservers;

   269 

   270     // Delay before popup show

   271     TInt iTimeDelayBeforeShow; // in microseconds

   272 

   273     // How long popup is shown

   274     TInt iTimeInView; // in microseconds

   275 

   276     // Specifies the tone

   277     TTone iTone;

   278     };

   279 

   280 #endif // CAKNINFOPOPUPNOTECONTROLLER_H

   281 

   282 

   283 // End of File